文本 API

Chat 对话、Legacy 补全与 Responses 对话，支持 SSE 流式输出

文本接口提供 Chat 对话、Legacy 文本补全与 Responses 对话三种能力，均支持非流式 JSON 与 SSE 流式输出。

能力概述

云擎数智网关提供三条文本类接口，按场景选择：

接口	适用场景	端点类型
`POST /v1/chat/completions`	通用对话、工具调用、多模态输入（图片等）、流式 SSE	`openai`
`POST /v1/completions`	Legacy 文本补全（prompt → 续写）	`openai`
`POST /v1/responses`	多轮 Responses 对话、推理、结构化输出、工具调用	`openai-response`

选型建议：

大多数新项目优先使用 Chat Completions（/v1/chat/completions）。
仅需单段 prompt 续写、对接旧版 SDK 时使用 Completions（/v1/completions）。
需要 previous_response_id 多轮上下文、Responses 结构化输出时使用 Responses（/v1/responses）。

前置条件：model 须为模型 API 返回列表中、supported_endpoint_types 含对应端点类型的模型。

通用约定：鉴权、Base URL、Content-Type 等见通用约定。错误响应格式见通用约定。

接口一览

方法	路径	说明
POST	`/v1/chat/completions`	Chat 对话（支持 SSE 流式）
POST	`/v1/completions`	文本补全
POST	`/v1/responses`	Responses 对话

POST `/v1/chat/completions`

Chat 对话，支持非流式 JSON 与 SSE 流式。

鉴权：Bearer Token

Content-Type：application/json

请求体

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, who are you?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

请求字段

字段	类型	必填	说明
`model`	string	是	模型 ID
`messages`	array	是	对话消息列表
`messages[].role`	string	是	`system` / `user` / `assistant` / `tool`
`messages[].content`	string / array	是	文本或多模态内容
`stream`	boolean	否	`true` 时返回 SSE 流，默认 `false`
`temperature`	number	否	采样温度，0–2
`top_p`	number	否	核采样，0–1
`max_tokens`	integer	否	最大输出 Token 数
`max_completion_tokens`	integer	否	最大补全 Token 数
`stop`	string / array	否	停止序列
`tools`	array	否	工具定义列表
`tool_choice`	string / object	否	工具选择策略
`response_format`	object	否	结构化输出格式
`stream_options`	object	否	流式选项，如 `{ "include_usage": true }`

多模态消息示例（图片输入）：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this image?" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.jpg" }
        }
      ]
    }
  ]
}

请求示例（curl）

非流式：

curl https://www.yunsell.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, who are you?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

流式（SSE）：

curl -N https://www.yunsell.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

响应体（非流式）

HTTP 200，Content-Type: application/json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm an AI assistant. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 15,
    "total_tokens": 43
  }
}

响应字段

字段	类型	说明
`id`	string	响应 ID，如 `chatcmpl-xxx`
`object`	string	固定为 `chat.completion`
`created`	integer	Unix 时间戳（秒）
`model`	string	实际使用的模型
`choices`	array	生成结果列表，长度等于请求中的 `n`（默认 1）
`choices[].index`	integer	结果索引，从 0 开始
`choices[].message.role`	string	固定为 `assistant`
`choices[].message.content`	string / null	回复文本；工具调用时可能为 `null`
`choices[].message.tool_calls`	array	工具调用列表（启用 tools 时）
`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 字符串
`choices[].message.reasoning_content`	string	推理过程文本（推理模型）
`choices[].finish_reason`	string	结束原因，见下表
`usage`	object	Token 用量，见公共响应对象

finish_reason 取值：

值	说明
`stop`	自然结束或命中 stop 序列
`length`	达到 `max_tokens` 上限
`tool_calls`	模型发起工具调用
`content_filter`	内容被安全策略拦截

工具调用响应示例：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\":\"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 20,
    "total_tokens": 70
  }
}

响应体（流式）

HTTP 200，Content-Type: text/event-stream

请求体设置 "stream": true 后，服务端以 SSE 推送，每条消息格式：

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

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

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":28,"completion_tokens":15,"total_tokens":43}}

data: [DONE]

流式 chunk 字段

字段	类型	说明
`id`	string	与最终响应相同的 ID
`object`	string	固定为 `chat.completion.chunk`
`created`	integer	Unix 时间戳（秒）
`model`	string	使用的模型
`system_fingerprint`	string	系统指纹（部分模型返回）
`choices[].index`	integer	结果索引
`choices[].delta.role`	string	首条 chunk 可能含 `assistant`
`choices[].delta.content`	string	增量文本片段
`choices[].delta.reasoning_content`	string	增量推理文本（推理模型）
`choices[].delta.tool_calls`	array	增量工具调用片段
`choices[].finish_reason`	string / null	末条 chunk 为结束原因，其余为 `null`
`usage`	object	仅末条 chunk 出现（需 `stream_options.include_usage=true`）

流式结束标志：最后一行 data: [DONE]。

POST `/v1/completions`

Legacy 文本补全接口。

鉴权：Bearer Token

Content-Type：application/json

请求体

{
  "model": "gpt-4o",
  "prompt": "Say this is a test",
  "max_tokens": 100,
  "temperature": 0.7,
  "stream": false
}

请求字段

字段	类型	必填	说明
`model`	string	是	模型 ID
`prompt`	string / array	是	提示文本
`max_tokens`	integer	否	最大输出 Token 数
`temperature`	number	否	采样温度
`top_p`	number	否	核采样
`n`	integer	否	生成数量，默认 1
`stream`	boolean	否	是否流式
`stop`	string / array	否	停止序列

请求示例（curl）

非流式：

curl https://www.yunsell.com/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "max_tokens": 100,
    "temperature": 0.7,
    "stream": false
  }'

流式（SSE）：

curl -N https://www.yunsell.com/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "stream": true
  }'

响应体（非流式）

HTTP 200

{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "text": "This is indeed a test.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 6,
    "total_tokens": 11
  }
}

响应字段

字段	类型	说明
`id`	string	响应 ID，如 `cmpl-xxx`
`object`	string	固定为 `text_completion`
`created`	integer	Unix 时间戳（秒）
`model`	string	使用的模型
`choices`	array	生成结果列表
`choices[].index`	integer	结果索引
`choices[].text`	string	补全文本
`choices[].finish_reason`	string	`stop` / `length` / `content_filter`
`usage`	object	Token 用量，见公共响应对象

响应体（流式）

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":"This","finish_reason":null}]}

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":" is","finish_reason":null}]}

data: [DONE]

流式 chunk 字段

字段	类型	说明
`id`	string	响应 ID
`object`	string	固定为 `text_completion`
`created`	integer	Unix 时间戳（秒）
`choices[].index`	integer	结果索引
`choices[].text`	string	增量文本片段
`choices[].finish_reason`	string / null	末条 chunk 为结束原因

POST `/v1/responses`

Responses 对话接口，支持多轮对话、工具调用、推理等。

鉴权：Bearer Token

Content-Type：application/json

请求体

{
  "model": "gpt-4o",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain quantum computing in one sentence."
        }
      ]
    }
  ],
  "temperature": 0.7,
  "max_output_tokens": 1024,
  "stream": false
}

请求字段

字段	类型	必填	说明
`model`	string	是	模型 ID
`input`	string / array	是	输入内容；可为字符串或消息数组
`instructions`	string	否	系统指令
`temperature`	number	否	采样温度
`max_output_tokens`	integer	否	最大输出 Token 数
`stream`	boolean	否	是否流式
`tools`	array	否	工具定义
`tool_choice`	string / object	否	工具选择策略
`previous_response_id`	string	否	上一轮响应 ID，用于多轮对话
`store`	boolean	否	是否存储对话
`metadata`	object	否	自定义元数据

请求示例（curl）

非流式：

curl https://www.yunsell.com/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Explain quantum computing in one sentence."}
        ]
      }
    ],
    "temperature": 0.7,
    "max_output_tokens": 1024,
    "stream": false
  }'

流式（SSE）：

curl -N https://www.yunsell.com/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Hello",
    "stream": true
  }'

响应体（非流式）

HTTP 200

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1712697600,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses quantum bits that can exist in superposition to perform certain calculations exponentially faster than classical computers.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 28,
    "total_tokens": 43
  },
  "temperature": 0.7,
  "top_p": 1.0
}

响应字段

字段	类型	说明
`id`	string	响应 ID，如 `resp_xxx`
`object`	string	固定为 `response`
`created_at`	integer	Unix 时间戳（秒）
`status`	string	响应状态，见下表
`model`	string	使用的模型
`output`	array	输出项列表
`output[].type`	string	输出类型，见下表
`output[].id`	string	输出项 ID
`output[].status`	string	输出项状态
`output[].role`	string	角色（`message` 类型时为 `assistant`）
`output[].content`	array	内容块列表
`output[].content[].type`	string	内容类型，如 `output_text`
`output[].content[].text`	string	文本内容
`output[].content[].annotations`	array	注释/引用列表
`output[].call_id`	string	工具调用 ID（`function_call` 类型）
`output[].name`	string	函数名（`function_call` 类型）
`output[].arguments`	string / object	函数参数（`function_call` 类型）
`output[].quality`	string	图像质量（`image_generation_call` 类型）
`output[].size`	string	图像尺寸（`image_generation_call` 类型）
`instructions`	string	系统指令（回显）
`temperature`	number	采样温度（回显）
`top_p`	number	核采样（回显）
`max_output_tokens`	integer	最大输出 Token（回显）
`previous_response_id`	string	上一轮响应 ID
`parallel_tool_calls`	boolean	是否并行工具调用
`store`	boolean	是否存储对话
`metadata`	object	自定义元数据
`incomplete_details.reason`	string	未完成原因（`status=incomplete` 时）
`error`	object	错误信息（`status=failed` 时）
`usage`	object	Token 用量，见公共响应对象

status 取值：

值	说明
`completed`	生成完成
`in_progress`	生成中
`failed`	生成失败
`incomplete`	因 Token 上限等原因未完成

output[].type 取值：

值	说明
`message`	助手文本消息
`function_call`	函数/工具调用
`image_generation_call`	图像生成调用
`web_search_call`	联网搜索调用

响应体（流式）

HTTP 200，Content-Type: text/event-stream

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}

data: {"type":"response.output_text.delta","delta":"Quantum","output_index":0,"content_index":0}

data: {"type":"response.output_text.delta","delta":" computing","output_index":0,"content_index":0}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":15,"output_tokens":28,"total_tokens":43}}}

data: [DONE]

流式事件字段

字段	类型	说明
`type`	string	事件类型，见下表
`response`	object	完整或部分响应对象
`delta`	string	增量文本
`output_index`	integer	输出项索引
`content_index`	integer	内容块索引
`item`	object	新增/完成的输出项
`item_id`	string	输出项 ID
`part`	object	推理摘要片段

常见 type 取值：

值	说明
`response.created`	响应创建
`response.output_text.delta`	文本增量
`response.output_item.added`	新增输出项
`response.output_item.done`	输出项完成
`response.function_call_arguments.delta`	函数参数增量
`response.function_call_arguments.done`	函数参数完成
`response.completed`	响应完成

模型 API

查询 API Key 可见的模型列表及各模型支持的端点类型

图像 API

文生图与图生图/编辑，同步返回图片 URL 或 Base64 数据