> ## 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.

# OpenAI Chat

> Use Chat Completions for text conversations and streaming responses.

## Endpoint

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

Set the OpenAI SDK `base_url` to `https://api.viviai.cc/v1`. The SDK appends `/chat/completions`.

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Use your ViVi-API key and replace `YOUR_OPENAI_MODEL` with an available Chat Completions model ID.

## Request parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Complete model ID. |
| `messages` | array | Yes | Messages in conversation order. |
| `messages[].role` | string | Yes | Usually user or assistant; instruction roles depend on the model. |
| `messages[].content` | string / array | Yes\* | Text or supported content blocks. |
| `stream` | boolean | No | Request SSE output with true. |
| `max_completion_tokens` | integer | No | Generation limit; reasoning tokens may count toward this limit. |
| `temperature` | number | No | Sampling control; support and range depend on the model. |
| `top_p` | number | No | Nucleus sampling; usually adjust this or temperature. |

\*Tool-only assistant messages can use a different structure. Some older models require `max_tokens` instead of `max_completion_tokens`; do not send both. Tool calling, multimodal input, reasoning, and structured output depend on the model and channel.

## 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 the SDK with `python -m pip install openai`. cURL uses Bash syntax.

```bash cURL theme={null}
curl --fail-with-body https://api.viviai.cc/v1/chat/completions \
  -H "Authorization: Bearer $VIVI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_OPENAI_MODEL",
    "messages": [
      {"role": "user", "content": "Explain APIs in three sentences."}
    ],
    "stream": false
  }'
```

```python Python SDK theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VIVI_API_KEY"],
    base_url="https://api.viviai.cc/v1",
    timeout=120.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="YOUR_OPENAI_MODEL",
    messages=[{"role": "user", "content": "Explain APIs in three sentences."}],
)
print(response.choices[0].message.content)
```

The examples disable automatic SDK retries to make initial troubleshooting easier.

## Response

Illustrative response; text and usage numbers are examples:

```json theme={null}
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "YOUR_OPENAI_MODEL",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "An API is an interface that applications use to communicate."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 20, "completion_tokens": 15, "total_tokens": 35}
}
```

* Text: `choices[0].message.content`.
* Finish reason: `choices[0].finish_reason`. `stop` usually means normal completion; `length` means the output limit was reached.
* Usage: `usage`. Exact fields and billing rules depend on the actual response and dashboard.

## Multi-turn conversations

Send the relevant conversation history with each request. The API key does not automatically associate requests with a conversation.

```json theme={null}
{
  "model": "YOUR_OPENAI_MODEL",
  "messages": [
    {"role": "user", "content": "I am learning Python."},
    {"role": "assistant", "content": "What would you like to learn first?"},
    {"role": "user", "content": "Explain lists."}
  ]
}
```

## Streaming

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["VIVI_API_KEY"],
    base_url="https://api.viviai.cc/v1",
    timeout=120.0,
    max_retries=0,
)

stream = client.chat.completions.create(
    model="YOUR_OPENAI_MODEL",
    messages=[{"role": "user", "content": "Write a short welcome message."}],
    stream=True,
)
try:
    for chunk in stream:
        if chunk.choices:
            text = chunk.choices[0].delta.content
            if text:
                print(text, end="", flush=True)
finally:
    stream.close()
print()
```

When parsing raw SSE, decode the JSON in each `data:` event and read `choices[0].delta.content`. Some events only carry a role or finish reason. A common final marker is `data: [DONE]`.

## Integration notes

* Include `/v1` only once in the final URL.
* Specialized image and other models may not support this endpoint.
* If parameters fail, start with only `model` and `messages`.
* See [troubleshooting](https://docs.viviai.cc/en/faq.md) for authentication, permission, and rate-limit errors.

Protocol reference: [OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create). Model availability and optional features depend on ViVi-API support.


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