协议与接口
Chat Completions
POST /v1/chat/completions 的请求参数、响应格式与兼容说明。
ModelTown 首版只提供 OpenAI Chat Completions 协议。所有模型都通过这一个接口调用，用 model 选择模型。
POST https://api.example.cn/v1/chat/completions
Authorization: Bearer sk-relay-xxxxxxxx
Content-Type: application/json请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
model | string | 必填。模型广场里的模型 ID，例如 qwen3.8-max。不支持模糊匹配，ID 写错直接返回 404 |
messages | array | 必填。对话消息，role 为 system、user、assistant 或 tool |
stream | boolean | 是否流式返回，见 流式输出 |
max_tokens | integer | 本次最多生成的 tokens。不填时按模型默认值，平台会据此预留余额 |
temperature、top_p | number | 采样参数，原样转发给上游 |
tools、tool_choice | array、string | 工具调用，见 工具调用 |
response_format | object | 结构化输出，见 结构化输出 |
stop | string | array | 停止词 |
模型不支持的能力（例如给纯文本模型传图片），平台会在发给上游之前直接拒绝，不产生费用。
响应
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "qwen3.8-max",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "……" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1240,
"completion_tokens": 186,
"total_tokens": 1426,
"prompt_tokens_details": { "cached_tokens": 0 }
}
}usage是扣费依据，cached_tokens是缓存命中的输入 tokens（已包含在prompt_tokens里）。- 响应头
X-Request-ID是平台为这次请求生成的唯一编号。排查问题、联系支持时请提供它。你自己传入的X-Request-ID只作为关联字段保存，不会替代平台编号。
与 OpenAI 的差异
- 只支持模型广场里列出的模型，不支持
gpt-*等 OpenAI 模型名。 - 平台默认不自动重试、不切换线路。上游出错时直接返回错误，由你决定是否重试，见 失败请求如何收费。
- 不同上游对少数参数的支持不完全一致，例如
logprobs、n > 1。不支持时会返回 400 并说明原因。