> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viviai.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic native API

> Use the Messages protocol with system instructions, token limits, and streaming.

## Endpoint

```http theme={null}
POST https://api.viviai.cc/v1/messages
```

## Authentication and API version

```http theme={null}
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json
```

Use your ViVi-API key. These examples use the `2023-06-01` Messages format. Change the version if your model or channel requires it; a new upstream version does not automatically mean the gateway supports it.

> [!NOTE]
>
> Replace `YOUR_ANTHROPIC_MODEL` with an available model ID that supports Anthropic Messages.

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Complete model ID. |
| `max_tokens` | integer | Yes | Maximum generated tokens. Examples use 1024. |
| `messages` | array | Yes | User and assistant messages in order. |
| `messages[].role` | string | Yes | user or assistant. |
| `messages[].content` | string / array | Yes | Text or supported content blocks. |
| `system` | string / array | No | Top-level system instructions. |
| `stream` | boolean | No | Request SSE output with true. |
| `temperature` | number | No | Sampling control, if the model supports it. |
| `stop_sequences` | array | No | Custom stop strings. |

Put instructions in the top-level `system` field, not in a message with `role: "system"`. Tools, thinking, and multimodal features require model and channel support.

## Request examples

Set `VIVI_API_KEY` to your ViVi-API key in your shell environment. See [Quickstart](https://docs.viviai.cc/en/index.md) to create a key. Install requests with `python -m pip install requests`. cURL uses Bash syntax.

```bash cURL theme={null}
curl --fail-with-body https://api.viviai.cc/v1/messages \
  -H "x-api-key: $VIVI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ANTHROPIC_MODEL",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain APIs in three sentences."}
    ]
  }'
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.viviai.cc/v1/messages",
    headers={
        "x-api-key": os.environ["VIVI_API_KEY"],
        "anthropic-version": "2023-06-01",
    },
    json={
        "model": "YOUR_ANTHROPIC_MODEL",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Explain APIs in three sentences."}],
    },
    timeout=120,
)
response.raise_for_status()
data = response.json()
print("".join(
    block["text"] for block in data.get("content", [])
    if block.get("type") == "text"
))
```

## Response

Illustrative response:

```json theme={null}
{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "YOUR_ANTHROPIC_MODEL",
  "content": [{"type": "text", "text": "An API is an interface that applications use to communicate."}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 20, "output_tokens": 15}
}
```

| Field | Description |
| - | - |
| `content` | Output content blocks. These examples read blocks with `type: "text"`. |
| `stop_reason` | `end_turn` means the turn ended; `max_tokens` means the generation limit was reached. |
| `usage` | Input and output token usage. Additional fields depend on the model and enabled features. |

Tool calls may return `tool_use` blocks and a corresponding stop reason. Do not treat these blocks as plain text.

## System instructions and multi-turn conversations

```json theme={null}
{
  "model": "YOUR_ANTHROPIC_MODEL",
  "max_tokens": 1024,
  "system": "You are a patient programming assistant. Answer in English.",
  "messages": [
    {"role": "user", "content": "I am learning Python."},
    {"role": "assistant", "content": "What would you like to learn first?"},
    {"role": "user", "content": "Explain lists."}
  ]
}
```

Send relevant history with every request. Context and output limits depend on the selected model.

## Streaming

```bash theme={null}
curl --no-buffer --fail-with-body https://api.viviai.cc/v1/messages \
  -H "x-api-key: $VIVI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_ANTHROPIC_MODEL",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a short welcome message."}]
  }'
```

Common event order: `message_start` → `content_block_start` → `content_block_delta` → `content_block_stop` → `message_delta` → `message_stop`. `ping` or error events may appear between them.

```text theme={null}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
```

Read `delta.text` only when `delta.type` is `text_delta`. Tool and thinking deltas use other structures. A stream can fail after the initial HTTP 200 response, so handle error events.

## Integration notes

* `max_tokens` is required.
* Send the protocol version in the `anthropic-version` header.
* Output is in `content`, not `choices[0].message.content`.
* Read the error body and check [troubleshooting](https://docs.viviai.cc/en/faq.md).

Protocol references: [Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create) and [API versioning](https://platform.claude.com/docs/en/api/versioning). Availability depends on ViVi-API support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.