# Chat Completions (/docs/chat-completions)


## Endpoint [#endpoint]

```
POST /v1/chat/completions
```

The Chat Completions API is the primary endpoint for text generation. It is fully compatible with the OpenAI Chat Completions format, allowing you to use any OpenAI SDK client.

## Request Body [#request-body]

```json
{
  "model": "model-id",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}
```

### Parameters [#parameters]

| Parameter           | Type          | Required | Description                                               |
| ------------------- | ------------- | -------- | --------------------------------------------------------- |
| `model`             | string        | Yes      | Model ID to use (query `/v1/models` for available models) |
| `messages`          | array         | Yes      | Array of message objects                                  |
| `temperature`       | number        | No       | Sampling temperature (0–2). Default: 1                    |
| `max_tokens`        | integer       | No       | Maximum tokens to generate                                |
| `top_p`             | number        | No       | Nucleus sampling parameter (0–1)                          |
| `stream`            | boolean       | No       | Enable streaming. Default: false                          |
| `stop`              | string/array  | No       | Stop sequences                                            |
| `frequency_penalty` | number        | No       | Frequency penalty (-2 to 2)                               |
| `presence_penalty`  | number        | No       | Presence penalty (-2 to 2)                                |
| `tools`             | array         | No       | Available function tools                                  |
| `tool_choice`       | string/object | No       | Tool selection strategy                                   |
| `response_format`   | object        | No       | Output format (e.g., `{"type": "json_object"}`)           |

### Message Object [#message-object]

| Field          | Type         | Required | Description                                |
| -------------- | ------------ | -------- | ------------------------------------------ |
| `role`         | string       | Yes      | `system`, `user`, `assistant`, or `tool`   |
| `content`      | string/array | Yes      | Message content (text or multimodal array) |
| `name`         | string       | No       | Name of the participant                    |
| `tool_calls`   | array        | No       | Tool calls made by the assistant           |
| `tool_call_id` | string       | No       | ID of the tool call being responded to     |

## Response [#response]

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709251200,
  "model": "model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 8,
    "total_tokens": 33
  }
}
```

## Examples [#examples]

### Basic Conversation [#basic-conversation]

<Tabs items="[&#x22;Python&#x22;, &#x22;JavaScript&#x22;, &#x22;cURL&#x22;]">
  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.yuhuanstudio.com/v1"
    )

    response = client.chat.completions.create(
        model="model-id",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Explain quantum computing in simple terms."}
        ],
        temperature=0.7,
        max_tokens=500
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab value="JavaScript">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({
      apiKey: "YOUR_API_KEY",
      baseURL: "https://api.yuhuanstudio.com/v1",
    });

    const response = await client.chat.completions.create({
      model: "model-id",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "Explain quantum computing in simple terms." },
      ],
      temperature: 0.7,
      max_tokens: 500,
    });

    console.log(response.choices[0].message.content);
    ```
  </Tab>

  <Tab value="cURL">
    ```bash
    curl https://api.yuhuanstudio.com/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "model": "model-id",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Explain quantum computing in simple terms."}
        ],
        "temperature": 0.7,
        "max_tokens": 500
      }'
    ```
  </Tab>
</Tabs>

### JSON Mode [#json-mode]

Force the model to output valid JSON:

```python
response = client.chat.completions.create(
    model="model-id",
    messages=[
        {"role": "system", "content": "Output JSON only."},
        {"role": "user", "content": "List 3 programming languages with their year of creation."}
    ],
    response_format={"type": "json_object"}
)
```

### Multi-Turn Conversation [#multi-turn-conversation]

```python
messages = [
    {"role": "system", "content": "You are a math tutor."},
    {"role": "user", "content": "What is a derivative?"},
    {"role": "assistant", "content": "A derivative measures the rate of change of a function..."},
    {"role": "user", "content": "Can you give me an example?"}
]

response = client.chat.completions.create(
    model="model-id",
    messages=messages
)
```

## Multimodal Messages [#multimodal-messages]

The `content` field of a message supports an array of content parts, enabling you to send text, images, documents, and videos in a single request.

### Content Types [#content-types]

| Type        | Description                      | Example                                                      |
| ----------- | -------------------------------- | ------------------------------------------------------------ |
| `text`      | Plain text content               | `{"type": "text", "text": "Describe this image"}`            |
| `image_url` | Image via URL or base64 data URI | `{"type": "image_url", "image_url": {"url": "https://..."}}` |
| `video_url` | Video via URL                    | `{"type": "video_url", "video_url": {"url": "https://..."}}` |
| `file_url`  | Document/file via URL            | `{"type": "file_url", "file_url": {"url": "https://..."}}`   |

### Image Input [#image-input]

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "What's in this image?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
  ]
}
```

Images can be provided as HTTPS URLs or base64 data URIs:

```python
import base64

with open("image.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="model-id",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image."},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
        ]
    }]
)
```

### Document Input [#document-input]

Attach documents (PDFs, text files, etc.) for analysis using `file_url`:

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize this document."},
    {"type": "file_url", "file_url": {"url": "https://example.com/report.pdf"}}
  ]
}
```

You can also use files uploaded via the [File API](/docs/files):

```python
# Upload a file first
file = client.files.create(
    file=open("report.pdf", "rb"),
    purpose="assistants"
)

# Then reference it in a chat message
response = client.chat.completions.create(
    model="model-id",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Summarize this report."},
            {"type": "file_url", "file_url": {"url": f"https://api.yuhuanstudio.com/v1/files/{file.id}/content"}}
        ]
    }]
)
```

### Video Input [#video-input]

```json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "Describe what happens in this video."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}
  ]
}
```

<Callout type="info">
  Not all models support all content types. Use the `GET /v1/models` endpoint and check the model's `capabilities` array (e.g., `vision`) to determine which content types a model supports.
</Callout>