/v1/chat/completions

POST https://ai-api.mandao.com/v1/chat/completions

发起内容生成请求，OpenAI Chat Completions 格式。支持文本对话、工具调用、流式输出等功能。

请求参数

Header 参数

参数名 类型 必需 说明
Authorization string 是 Bearer Token 认证。格式：Bearer <your-api-key>
Content-Type string 是 application/json

Body 参数 (application/json)

参数名 类型 必需 默认值 说明
model string 是 - 模型 ID，如 gpt-4o、gpt-5.1 等
messages array[object] 是 - 对话消息列表
messages[].role string 是 - 角色：system、user、assistant、developer（GPT-5 系列）
messages[].content string 或 array[object] 是 - 消息内容，支持纯文本和多模态内容（图片、音频、文件）
max_tokens integer 否 - 最大生成 token 数（GPT-5 系列会自动转换为 max_completion_tokens）
max_completion_tokens integer 否 - 最大生成 token 数（推荐 GPT-5 系列使用）
temperature number 否 - 采样温度，范围 0~2。GPT-5 系列固定为 1
top_p number 否 - 核采样参数，范围 0~1
top_k integer 否 - Top-K 采样参数
stream boolean 否 false 是否启用流式输出
stream_options object 否 - 流式输出选项，如 include_usage
stop string 或 array[string] 否 - 停止词
n integer 否 - 生成候选数量
frequency_penalty number 否 - 频率惩罚，范围 -2.0~2.0
presence_penalty number 否 - 存在惩罚，范围 -2.0~2.0
tools array[object] 否 - 工具定义列表（函数调用）
tool_choice string 或 object 否 - 工具选择策略
response_format object 否 - 响应格式（如 JSON 模式）
seed integer 否 - 随机种子
reasoning_effort string 否 - 推理力度（GPT-5 系列）
verbosity string 否 - 输出详细程度（GPT-5 系列）
modalities array[string] 否 - 输出模态（如 ["text"]）
audio object 否 - 音频输出配置
logprobs boolean 否 - 是否返回对数概率
top_logprobs integer 否 - 返回概率最高的 token 数
user string 否 - 用户标识

多模态消息格式

文本消息

{
    "role": "user",
    "content": "帮我写一首诗"
}

图片消息

{
    "role": "user",
    "content": [
        {"type": "text", "text": "描述这张图片"},
        {"type": "image_url", "image_url": {"url": "https://example.com/image.png", "detail": "high"}}
    ]
}

音频消息

{
    "role": "user",
    "content": [
        {"type": "text", "text": "转写这段音频"},
        {"type": "input_audio", "input_audio": {"data": "<base64>", "format": "wav"}}
    ]
}

请求示例

curl --location 'https://ai-api.mandao.com/v1/chat/completions' \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "帮我写一首诗"
        }
    ],
    "max_tokens": 2048,
    "temperature": 0.7,
    "stream": false
}'

返回响应

200 成功

非流式响应：

{
    "id": "chatcmpl-xxx",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "gpt-4o",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "春风拂面柳如烟..."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 42,
        "total_tokens": 57
    }
}

流式响应（SSE）：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1700000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}

data: [DONE]

错误响应

{
    "error": {
        "message": "错误描述信息",
        "type": "invalid_request_error",
        "param": "model",
        "code": "invalid_model"
    }
}

注意事项

  • GPT-5/5.1 家族不支持 max_tokens，推荐使用 max_completion_tokens。平台会自动将 max_tokens 转为 max_completion_tokens。
  • GPT-5 家族不支持指定 temperature，固定为 1。
  • GPT-5 系列的 system 角色请使用 developer 替代。
  • 支持 SSE（Server-Sent Events）流式输出。