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

# 创建 chat completion

> 通过 OpenAI 兼容的 Chat Completions 形状向 Manyfold Agent 发起一个 turn。

Source: https://docs.manyfold.ai/zh/api-reference/chat-completions/

```http
POST /api/v1/chat/completions
```

认证: Bearer API token，scope 为 chat.completions 或 api.full。
配额: 计入每月 API request 配额。

## 参数

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `model` | 必填 | Manyfold agent id，例如 agt_... |
| `messages` | 必填 | 支持 system/developer/user/assistant role；user 消息可包含 image_url 和 file 内容块。 |
| `stream` | 可选 | 设为 true 时返回 Server-Sent Events。 |
| `metadata.session_id` | 可选 | 继续此前 turn 返回的 Manyfold session。 |
| `stream_options.include_usage` | 可选 | 设为 true 时，如果有用量数据，流式响应可包含最终 usage chunk。 |

## 请求

```bash
curl https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "messages": [
      { "role": "user", "content": "Summarize this repository." }
    ]
  }'
```

## 流式响应

```bash
curl -N https://api.manyfold.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $MF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agt_your_agent_id",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [
      { "role": "user", "content": "Write a short release note." }
    ]
  }'
```

## 响应

```json
{
    "object": "chat.completion",
    "model": "agt_your_agent_id",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "..."
            },
            "finish_reason": "stop"
        }
    ],
    "metadata": {
        "session_id": "cts_...",
        "assistant_message_id": "..."
    }
}
```

## 响应

- 非流式响应返回 chat.completion，可读取 choices[0].message.content。
- metadata.session_id 和 x-session-id 用于识别 Manyfold 会话。
- 流式响应发送 chat.completion.chunk event，最后是 data: [DONE]。