对话补全 API​

POST https://api.yu-yu.ai/v1/chat/completions

对话补全接口用于向对话模型发送一段或多段消息，并获取模型生成的回复。本接口兼容通用的对话补全调用协议，本网关中所有以对话方式调用的模型均通过本接口访问，例如文本对话、多模态理解等模型。

调用前请先在 https://api.yu-yu.ai/console 确认目标模型名称与可用状态，模型名请直接使用控制台中展示的模型 ID。

鉴权​

本接口使用 API Key 鉴权。请在 https://api.yu-yu.ai/console 获取 API Key，并在请求头中携带：

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求参数​

Body 参数​

请求体为 JSON。除 model 与 messages 外，其余字段均为可选，可按需传入。

model string 必选

要调用的模型 ID。取值请使用调用方在 https://api.yu-yu.ai/console 中看到的模型名称，例如 deepseek-v4.1-flash、gpt-4o、qwen-max。

请不要填写展示名称、自己的备注或供应商名称，模型名需与控制台完全一致。

messages object[] 必选

对话消息列表，按时间顺序排列，至少包含 1 条消息。每条消息包含 role 与 content 两个核心子字段。

支持的角色：

• system：系统提示词，用于设定模型的身份、语气与约束。建议放在列表第一条。
• user：用户输入。
• assistant：模型此前的回复，用于构造多轮对话上下文。
• tool：工具调用结果回传，需配合 tool_call_id 使用。

子字段说明：

• messages.role string 必选：消息角色，取值 system / user / assistant / tool。
• messages.content string | object[] 必选：消息内容。纯文本场景直接传字符串；多模态场景传内容数组。
• messages.name string 可选：参与者名称，用于区分同一角色下的不同参与者。
• messages.tool_calls object[] 可选：assistant 消息中由模型产生的工具调用列表，用于多轮工具调用。
• messages.tool_call_id string 可选：tool 角色消息对应的工具调用 ID。

多模态 content 数组写法​

当 content 为数组时，数组元素按 type 区分，常见取值：

• text：文本片段，配 text 字段。
• image_url：图片片段，配 image_url 对象。

image_url 对象的子字段：

• content[].image_url.url string 必选：图片地址，支持公网可访问的图片 URL，或 data:image/<格式>;base64,<Base64编码> 形式的内联图片，例如 data:image/png;base64,{base64_image}。
• content[].image_url.detail string 可选：图片理解精细度。

{
  "model": "YOUR_MODEL",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请描述这张图片的内容。" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.png" }
        }
      ]
    }
  ]
}

temperature number 可选

采样温度，控制输出的随机性。取值范围 0 到 2，值越大输出越发散、越有创造性，值越小输出越稳定、越确定。默认值 1。

建议只调整 temperature 与 top_p 中的一个，不要同时大幅调整二者。

top_p number 可选

核采样参数，模型仅从累积概率达到 top_p 的候选词中采样。取值范围 0 到 1，默认值 1。值越小输出越保守。

建议只调整 temperature 与 top_p 中的一个。

max_tokens integer 可选

本次回复允许生成的最大 token 数。prompt 与生成内容的总长度受模型上下文长度限制。

不同模型的上限不同；未设置时，上限由所选模型决定。

max_completion_tokens integer 可选

与 max_tokens 作用相同，用于部分较新的模型。部分模型可能不接受该字段，如遇到参数报错，请改用 max_tokens。

stream boolean 可选

是否以流式方式返回结果，默认 false。

• false：一次性返回完整 JSON 响应体。
• true：以 Server-Sent Events（SSE）方式分块返回，最后以 data: [DONE] 结束。

stream_options object 可选

流式响应的附加选项，仅在 stream 为 true 时生效；若 stream 不为 true 而传入本字段，可能返回 400 错误。

• stream_options.include_usage boolean 可选：为 true 时，在流式响应中包含 token 用量统计信息。

stop string | string[] 可选

停止序列。模型生成到该内容时停止继续生成。可传单个字符串，也可传字符串数组。不同模型支持的最大停止序列数量不同。

n integer 可选

为每条输入消息生成的候选回复数量，默认 1。大于 1 时，响应中的 choices 会包含多个结果。并非所有模型都支持该字段。

response_format object 可选

指定模型的输出格式。

• response_format.type string 可选：输出格式类型。text 表示普通文本输出，json_object 表示要求模型输出合法 JSON 对象。
• response_format.json_schema object 可选：结构化输出使用的 JSON Schema 定义，仅在支持结构化输出的模型上生效。

tools object[] 可选

可供模型调用的工具列表。当前仅支持 function 类型，可以一次传入多个函数定义，函数名需唯一。

单个工具的子字段：

• tools[].type string 必选：工具类型，当前取值为 function。
• tools[].function object 必选：函数定义。
  • tools[].function.name string 必选：函数名，仅允许字母、数字、下划线与短横线，最大长度 128。
  • tools[].function.description string 可选：函数用途说明，模型据此判断何时调用该函数。
  • tools[].function.parameters object 可选：函数参数，使用 JSON Schema 描述。省略该字段表示函数无参数。

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询指定城市的天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "城市名称" }
      },
      "required": ["city"]
    }
  }
}

tool_choice string | object 可选

控制模型是否以及调用哪个工具。

• none：不调用任何工具，直接生成消息。
• auto：由模型自行决定是生成消息还是调用工具。
• required：强制模型调用一个或多个工具。
• 指定具体工具：传 {"type": "function", "function": {"name": "get_weather"}}，强制调用该函数。

未传入 tools 时默认 none；传入 tools 时默认 auto。

parallel_tool_calls boolean 可选

是否允许模型在一次回复中并行调用多个工具。关闭后模型每次最多调用一个工具。

frequency_penalty number 可选

频率惩罚，按 token 在文本中已出现的次数进行惩罚，降低模型逐字重复的概率。通常取值范围为 -2.0 到 2.0，默认 0。

presence_penalty number 可选

存在惩罚，按 token 是否已在文本中出现过进行惩罚，鼓励模型引入新话题。通常取值范围为 -2.0 到 2.0，默认 0。

logprobs boolean 可选

是否返回输出 token 的对数概率信息。为 true 时，响应中会包含 logprobs 字段。

top_logprobs integer 可选

在每个 token 位置返回概率最高的候选 token 数量，取值范围 0 到 20。使用该字段时必须同时将 logprobs 设为 true。

seed integer 可选

随机种子。在相同参数与相同种子的情况下，接口会尽量返回相同结果，但不保证完全可复现，请勿将其用于需要严格确定性的场景。

user string 可选

调用方的终端用户标识，用于区分不同来源的请求，便于内容安全审查与问题排查。请勿在其中携带用户隐私信息。

响应参数​

非流式请求返回 application/json，主要字段如下。

id string

本次补全的唯一标识。

object string

对象类型，固定为 chat.completion。

created integer

响应创建时间的 Unix 时间戳（秒）。

model string

实际用于生成该响应的模型名称。

choices object[]

模型生成的候选回复列表，n 为 1 时通常只包含 1 个元素。

• choices[].index integer：该结果在列表中的序号。
• choices[].finish_reason string：生成停止原因。常见取值：
  • stop：正常结束，或命中了 stop 停止序列。
  • length：达到 max_tokens 或上下文长度上限，输出被截断。
  • tool_calls：模型决定调用工具。
  • content_filter：内容被安全策略过滤。
• choices[].message object：模型生成的消息。
  • choices[].message.role string：消息角色，固定为 assistant。
  • choices[].message.content string：模型回复的正文内容。
  • choices[].message.reasoning_content string：思维链内容。仅支持思考模式（推理）的模型会返回该字段，普通模型通常不返回。
  • choices[].message.tool_calls object[]：模型产生的工具调用列表。仅当 finish_reason 为 tool_calls 时返回。
    • choices[].message.tool_calls[].id string：工具调用 ID，回传工具结果时需要带上。
    • choices[].message.tool_calls[].type string：工具类型，当前为 function。
    • choices[].message.tool_calls[].function.name string：被调用的函数名。
    • choices[].message.tool_calls[].function.arguments string：函数参数的 JSON 字符串。该字符串不保证一定是合法 JSON，调用前请在代码中做校验。
• choices[].logprobs object：token 对数概率信息。仅当请求中 logprobs 为 true 时返回，否则可能为 null。

usage object

本次请求的 token 用量统计。

• usage.prompt_tokens integer：输入（提示）token 数。
• usage.completion_tokens integer：输出（生成）token 数。
• usage.total_tokens integer：总 token 数，等于输入与输出之和。
• usage.prompt_tokens_details object：输入 token 的明细，例如 cached_tokens 表示命中上下文缓存的 token 数。具体包含哪些明细字段取决于模型。
• usage.completion_tokens_details object：输出 token 的明细，例如 reasoning_tokens 表示推理消耗的 token 数。具体包含哪些明细字段取决于模型。

system_fingerprint string

后端配置的指纹信息，便于排查后端变更带来的结果差异。该字段不一定返回。

流式响应​

当请求体中 stream 为 true 时，接口以 SSE 方式返回，响应头为 Content-Type: text/event-stream。每个分块形如 data: {JSON}，最后以一行 data: [DONE] 结束。

分块结构与完整响应基本一致，区别在于 object 为 chat.completion.chunk，且增量内容位于 choices[].delta 中：

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

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_MODEL","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_MODEL","choices":[{"index":0,"delta":{"content":"，很高兴"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1710000000,"model":"YOUR_MODEL","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

分块字段说明：

• choices[].delta.role string：通常在第一个分块中出现，值为 assistant。
• choices[].delta.content string：本次分块新增的正文内容，需要按顺序拼接。最后一个分块可能不含 content。
• choices[].delta.reasoning_content string：思维链增量内容，仅推理模型可能返回。
• choices[].delta.tool_calls object[]：工具调用增量。流式场景下 function.arguments 会分多次返回，需要按 index 拼接后才是完整参数。
• choices[].finish_reason string：为 null 表示尚未结束；出现非空值表示本次生成结束。
• usage object：token 用量统计。未开启 stream_options.include_usage 时，通常只在最后一个分块中出现。

请求示例​

基础对话​

curl -X POST "https://api.yu-yu.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "请用一句话介绍你自己。"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

流式对话​

curl -N -X POST "https://api.yu-yu.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "messages": [
      {"role": "user", "content": "写一首关于秋天的五言绝句。"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

工具调用​

curl -X POST "https://api.yu-yu.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {"role": "user", "content": "北京今天天气怎么样？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "查询指定城市的天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string", "description": "城市名称"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

响应示例​

非流式响应的完整 JSON 结构：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是一个可以帮你解答问题、撰写文字和处理图片的 AI 助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

返回工具调用时的响应片段：

{
  "id": "chatcmpl-def456",
  "object": "chat.completion",
  "created": 1710000001,
  "model": "YOUR_MODEL",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"北京\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 88,
    "completion_tokens": 21,
    "total_tokens": 109
  }
}

常见错误​

接口错误通常返回如下结构：

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