# 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
)
```

Model Compatibility [#model-compatibility]

All chat-capable models work with this endpoint. Use the Models API to discover available models:

<Callout>
  Use the `GET /v1/models` endpoint to dynamically list all available models and their capabilities. Consider factors like context length, capabilities, and pricing when selecting a model.
</Callout>