*更新日期: 2026-10-10*

# 对话

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

支持**文本**、**Vision 图文**（OpenAI 兼容 `image_url` content part）、**文件附件**（OpenAI 兼容 `file` content part，`file_data` / 公网 URL）和 **function calling**。网关不执行函数，只把 `tools` 交给模型服务，并把 `tool_calls` 回给调用方。`response_format` 与 `web_search` 等内置工具会被拒绝或忽略：未列出的字段静默忽略；非 `function` 的 `tools` 返回 400。`file_id` / `/v1/files` 不可用，传入会返回 400。是否真正看图/读文件、是否会发起函数调用，取决于所选模型。

OpenAI Responses 形态见 [`POST /v1/responses`](/docs/responses)（同样支持 `input_image` / `input_file`）。

## 请求

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | 是 | 对外 id |
| `messages` | array | 是 | 至少一条。`role` 为 `system` / `user` / `assistant` / `tool`。助手调用函数时带 `tool_calls`，`content` 可为 `null`。`role: tool` 必须带 `tool_call_id` |
| `stream` | boolean | 否 | `true` 时 SSE；函数调用以 `delta.tool_calls` 分片返回 |
| `temperature` | number | 否 | 作用于所选模型 |
| `max_tokens` | number | 否 | 作用于所选模型 |
| `tools` | array | 否 | 仅 `type: "function"`。每项含 `function.name`，可选 `description` / `parameters` / `strict` |
| `tool_choice` | string \| object | 否 | `none` / `auto` / `required`，或 `{ "type": "function", "function": { "name": "..." } }`。设置时必须同时传 `tools` |
| `parallel_tool_calls` | boolean | 否 | 是否允许同一次回复里并行多个函数调用。设置时必须同时传 `tools` |

### `messages[].content`

| 形态 | 说明 |
|------|------|
| `string` | 纯文本 |
| `array` | content parts：`text`、`image_url`、`file`（见下） |

`image_url.url` 支持：

| 形态 | 说明 |
|------|------|
| 公网 URL | `https://...`（该地址需可公网访问） |
| Data URL / base64 | `data:image/png;base64,...`；网关先转存为平台公网 URL 再交给模型服务 |
| 对象简写 | `image_url` 也可直接为字符串 URL |

可选 `image_url.detail`（如 `low` / `high` / `auto`）作用于所选模型。

#### 文件 part（`type: "file"`）

| 字段 | 说明 |
|------|------|
| `file.file_data` | Data URL / base64，或公网 HTTPS URL；内嵌数据会先转存为平台公网 URL，再以 `file_data` 交给上游 |
| `file.filename` | 可选文件名（如 `doc.pdf`） |
| `file.file_id` | **不支持**（无 `/v1/files`），单独传入返回 400 |

本地文件路径不支持。请用 `file_data`（含 data URL）或公网 URL，不要传 `file_id`。

Vision 示例：

```json
{
  "model": "YOUR_CHAT_MODEL",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "图里有什么？" },
        {
          "type": "image_url",
          "image_url": { "url": "https://cdn.example.com/cat.png" }
        }
      ]
    }
  ]
}
```

Function calling 示例（调用方拿到 `tool_calls` 后自行执行，再把 `role: "tool"` 的结果发回）：

```json
{
  "model": "YOUR_CHAT_MODEL",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "巴黎天气如何？" }
  ]
}
```

同步响应里 `choices[0].message.tool_calls` 为函数调用，`finish_reason` 为 `tool_calls`。流式响应里参数在 `delta.tool_calls[].function.arguments` 中分段到达。

```bash
curl https://tokenmei.com/v1/chat/completions \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [
      {"role": "system", "content": "你是助手"},
      {"role": "user", "content": "你好"}
    ],
    "temperature": 0.7,
    "max_tokens": 2048
  }'
```

```javascript
const chat = await client.chat.completions.create({
  model: "YOUR_CHAT_MODEL",
  messages: [
    { role: "system", content: "你是助手" },
    { role: "user", content: "你好" },
  ],
  temperature: 0.7,
  max_tokens: 2048,
});
console.log(chat.id);
console.log(chat.choices[0].message.content);
console.log(chat.usage);
```

```python
chat = client.chat.completions.create(
    model="YOUR_CHAT_MODEL",
    messages=[
        {"role": "system", "content": "你是助手"},
        {"role": "user", "content": "你好"},
    ],
    temperature=0.7,
    max_tokens=2048,
)
print(chat.id)
print(chat.choices[0].message.content)
print(chat.usage)
```

```go
chat, _ := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
	Model: "YOUR_CHAT_MODEL",
	Messages: []openai.ChatCompletionMessageParamUnion{
		openai.SystemMessage("你是助手"),
		openai.UserMessage("你好"),
	},
	Temperature: openai.Float(0.7),
	MaxTokens:   openai.Int(2048),
})
fmt.Println(chat.ID)
fmt.Println(chat.Choices[0].Message.Content)
fmt.Println(chat.Usage)
```

```php
$chat = $client->chat()->create([
    "model" => "YOUR_CHAT_MODEL",
    "messages" => [
        ["role" => "system", "content" => "你是助手"],
        ["role" => "user", "content" => "你好"],
    ],
    "temperature" => 0.7,
    "max_tokens" => 2048,
]);
echo $chat->id, PHP_EOL;
echo $chat->choices[0]->message->content, PHP_EOL;
print_r($chat->usage);
```

```java
ChatCompletion chat = client.chat().completions().create(
    ChatCompletionCreateParams.builder()
        .model("YOUR_CHAT_MODEL")
        .addSystemMessage("你是助手")
        .addUserMessage("你好")
        .temperature(0.7)
        .maxTokens(2048)
        .build()
);
System.out.println(chat.id());
System.out.println(chat.choices().get(0).message().content());
System.out.println(chat.usage());
```

```csharp
var chat = client.GetChatClient("YOUR_CHAT_MODEL").CompleteChat(
    new SystemChatMessage("你是助手"),
    new UserChatMessage("你好"),
    new ChatCompletionOptions { Temperature = 0.7f, MaxOutputTokenCount = 2048 }
);
Console.WriteLine(chat.Id);
Console.WriteLine(chat.Content[0].Text);
Console.WriteLine(chat.Usage);
```

## 非流式响应

```json
{
  "id": "chatcmpl_a1b2c3d4e5f6",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "YOUR_CHAT_MODEL",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "你好！" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28,
    "cost": { "amount": "0.0021", "currency": "CNY" }
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 前缀固定 `chatcmpl_` |
| `object` | string | 固定 `chat.completion` |
| `created` | int | Unix 秒 |
| `model` | string | 对外模型 id |
| `choices` | array | 每项含 `index`、`message`、`finish_reason` |
| `choices[].message.role` | string | `assistant` |
| `choices[].message.content` | string | 回复文本 |
| `choices[].finish_reason` | string | 如 `stop` |
| `usage.prompt_tokens` | int | 输入 token |
| `usage.completion_tokens` | int | 输出 token |
| `usage.total_tokens` | int | 合计 |
| `usage.cost` | object | 可选。`amount` 为对外售价字符串，`currency` 为 `CNY`。运营可在系统设置里关闭，关闭后字段不出现 |

## 流式

`stream: true` 时 HTTP 仍是 **200**，`Content-Type: text/event-stream`。每帧 `data: {json}`，结束 `data: [DONE]`。最后一帧（`[DONE]` 之前）带 `usage` 与 `finish_reason`。扣费发生在流正常结束后，按实际消耗的 token（usage），不是按 `max_tokens`。

```bash
curl -N https://tokenmei.com/v1/chat/completions \
  -H "Authorization: Bearer $MOMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CHAT_MODEL",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

```javascript
const stream = await client.chat.completions.create({
  model: "YOUR_CHAT_MODEL",
  messages: [{ role: "user", content: "你好" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

```python
stream = client.chat.completions.create(
    model="YOUR_CHAT_MODEL",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

```go
stream := client.Chat.Completions.NewStreaming(context.TODO(), openai.ChatCompletionNewParams{
	Model: "YOUR_CHAT_MODEL",
	Messages: []openai.ChatCompletionMessageParamUnion{
		openai.UserMessage("你好"),
	},
})
for stream.Next() {
	chunk := stream.Current()
	if len(chunk.Choices) > 0 {
		fmt.Print(chunk.Choices[0].Delta.Content)
	}
}
```

```php
$stream = $client->chat()->createStreamed([
    "model" => "YOUR_CHAT_MODEL",
    "messages" => [["role" => "user", "content" => "你好"]],
]);
foreach ($stream as $chunk) {
    echo $chunk->choices[0]->delta->content ?? "";
}
```

```java
client.chat().completions().createStreaming(
    ChatCompletionCreateParams.builder()
        .model("YOUR_CHAT_MODEL")
        .addUserMessage("你好")
        .build()
).subscribe(chunk -> {
    if (!chunk.choices().isEmpty()) {
        chunk.choices().get(0).delta().content().ifPresent(System.out::print);
    }
});
```

```csharp
await foreach (var chunk in client.GetChatClient("YOUR_CHAT_MODEL")
    .CompleteChatStreamingAsync("你好")) {
    Console.Write(chunk.ContentUpdate[0].Text);
}
```

增量帧示例：

```
data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_CHAT_MODEL","choices":[{"index":0,"delta":{"content":"你"},"finish_reason":null}]}

data: {"id":"chatcmpl_…","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_CHAT_MODEL","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":8,"completion_tokens":2,"total_tokens":10}}

data: [DONE]
```

| 字段 | 说明 |
|------|------|
| `data: {json}` | 增量帧 |
| `choices[].delta.content` | 文本增量，可能为空 |
| 最后一帧 | `[DONE]` 之前，带 `usage` 与 `finish_reason` |
| `data: [DONE]` | 结束标记 |
| `data: {"error":…}` | 模型调用失败；HTTP 仍可能是 200，不扣费 |

模型调用失败时不要只看 HTTP 状态。失败的流不会扣费。中途断连以服务端是否跑完结算为准；不要假设客户端 abort 一定退款。
