OpenAI 兼容 Chat Completions 接入文档

流式/非流式对话与多模态输入

1. 概述

本接口提供 OpenAI 风格的 Chat Completions 能力,支持流式(SSE)非流式两种模式,通过请求体中的 stream 字段切换。

  • 标准地址:POST {baseUrl}/chat/completions
  • 鉴权:Authorization: Bearer <api_key>
  • 请求体:标准 OpenAI Chat Completions JSON

2. 接入前置条件

说明
api_key 访问密钥(控制台生成),用于 Bearer 鉴权。

3. 鉴权

Header 必填 说明
Authorization Bearer <api_key>
Content-Type application/json
Accept 流式建议 流式设 text/event-stream;非流式可设 application/json

缺失 Authorizationapi_key 无效时,直接返回 401


4. 对话补全

4.1 请求体

请求体采用标准 OpenAI Chat Completions JSON 结构:

字段 类型 必填 说明
model string 平台已开通的模型编码。
messages array 消息数组,结构见下文。
stream boolean true 为流式;false 或省略为非流式。
temperature number 采样温度。
max_tokens integer 最大生成 token 数。
max_completion_tokens integer 最大生成 token 数;同时传递时优先。
top_p number 核采样参数。
modalities array 输入模态,例如 ["text","image"]
enableThinking boolean 混合思考模型开关。

4.1.1 message 结构

JSON
{ "role": "user", "content": "你好" }

content 支持两种形式:

  • 字符串:"描述这张图"
  • 数组(多模态):由若干 content part 组成,见 4.1.2

role 可取:system / user / assistant

4.1.2 content part 类型(OpenAI 标准)

接口支持以下标准 OpenAI content part 类型:

客户端发送(OpenAI 标准) 说明
{"type":"text","text":"..."} 文本
{"type":"image_url","image_url":{"url":"..."}} 图片;url 支持公网地址或 data:image/...;base64,...
{"type":"input_audio","input_audio":{"data":"<base64>","format":"wav"}} 音频;data 为 Base64 数据,format 为音频格式。
{"type":"audio_url","audio_url":{"url":"..."}} 音频 URL

4.2 请求示例

4.2.1 非流式 · 纯文本

BASH
curl -X POST 'https://token.soar.qjclouds.cn/laserStreamEr/00000000/v1/chat/completions' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<modelCode>",
    "stream": false,
    "messages": [
      {"role":"system","content":"你是助手"},
      {"role":"user","content":"你好,用一句话介绍自己"}
    ]
  }'

4.2.2 流式 · 文本 + 图片(多模态)

BASH
curl -N -X POST 'https://token.soar.qjclouds.cn/laserStreamEr/00000000/v1/chat/completions' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "<modelCode>",
    "stream": true,
    "modalities": ["text","image"],
    "messages": [
      {
        "role": "user",
        "content": [
          {"type":"text","text":"描述这张图"},
          {"type":"image_url","image_url":{"url":"https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"}}
        ]
      }
    ]
  }'

4.2.3 图片 base64

JSON
{
  "type": "image_url",
  "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }
}

4.2.4 音频(input_audio)

JSON
{
  "type": "input_audio",
  "input_audio": { "data": "<base64>", "format": "wav" }
}

4.3 响应

4.3.1 非流式响应

  • HTTP 200
  • Content-Type: application/json
  • 单个 chat.completion 对象
JSON
{
  "id": "83db42cd-7fd9-95c0-badd-8169f26abf93",
  "object": "chat.completion",
  "created": 1721492158,
  "model": "<modelCode>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "您好" },
      "finishReason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 11, "completion_tokens": 1, "total_tokens": 12 }
}

4.3.2 流式响应

  • HTTP 200
  • Content-Type: text/event-stream
  • 每帧 data: <json>\n\n,末尾 data: [DONE]\n\n
TEXT
data: {"id":"...","object":"chat.completion.chunk","created":1721492158,"model":"<modelCode>","choices":[{"index":0,"delta":{"role":"assistant"},"finishReason":null}]}

data: {"id":"...","object":"chat.completion.chunk","created":1721492158,"model":"<modelCode>","choices":[{"index":0,"delta":{"content":"您"},"finishReason":null}]}

data: {"id":"...","object":"chat.completion.chunk","created":1721492158,"model":"<modelCode>","choices":[{"index":0,"delta":{},"finishReason":"stop"}]}

data: [DONE]

4.4 错误响应

错误体统一为 OpenAI 风格:

JSON
{
  "error": {
    "message": "missing API key",
    "type": "internal_error",
    "code": "StreamController.openAiChat.unauthorized"
  }
}

HTTP 状态码映射:

HTTP 触发场景
400 请求体为空 / 非法 JSON / 参数缺失(如 参数...为空is not passed)
401 缺失 Authorizationapi_key 无效
404 模型/路由/API 不存在(模型配置不存在API not exist)
429 限流 / 配额不足
500 其它服务端异常

流式已开始后的业务错误:以 SSE 错误帧 + data: [DONE] 结束,不会改 HTTP 状态码。

6. OpenAI SDK 接入示例

Python

PYTHON
"tk-key">from openai "tk-key">import
                            OpenAI

"tk-key">client = OpenAI(
    base_url="https://token.soar.qjclouds.cn/laserStreamEr/00000000/v1",
    api_key="<api_key>",
)

"tk-key">class="tk-com"># 非流式
                            resp = "tk-key">client
                            .chat.completions.create(
    model="<modelCode>",
    messages=[{"role":"user","content":"你好"}],
)
"tk-key">print(resp.choices[0].message.content)

"tk-key">class="tk-com"># 流式
                            "tk-key">for chunk "tk-key">in
                            "tk-key">client.chat.completions.create(
    model="<modelCode>",
    messages=[{"role":"user","content":"你好"}],
    stream="tk-key">True,
):
    delta = chunk.choices[0].delta.content
    "tk-key">if delta:
        "tk-key">print(delta, end="", flush="tk-key">True
                            )

Node.js

JS
"tk-key">import OpenAI "tk-key">from
                            "openai";

"tk-key">const client = "tk-key">new
                            OpenAI({
  baseURL: "https:">//token.soar.qjclouds.cn/laserStreamEr/00000000/v1",
                            apiKey: "<api_key>",
});

"tk-key">const resp = "tk-key">await
                            client.chat.completions.create({
  model: "<modelCode>",
  messages: [{ role: "user", content: "你好" }],
});
console.log(resp.choices[0].message.content);

Gemini Image 与 GPT Image 2 文生图/图生图。

说明:对话生图仅支持非流式请求,请将 stream 设置为 false

  • model:已在平台 ag_model 配置并开通的模型编码。
  • messages:必须包含至少一条 role=user 的消息,其中含文本提示词。
  • 图生图输入图使用 OpenAI 标准 image_url;支持公网 URL 或 data:image/...;base64,...
  • content 支持字符串或多模态 content part 数组。
  • Gemini Image 不支持 audio / video 类型输入,仅支持 textimage
字段 类型 必填 说明
model string 平台 ag_model 配置的模型编码
messages array 消息数组,必须含 user 文本提示词
stream boolean 固定 false,Gemini Image 不支持流式
temperature number 生成温度,范围 0.0–2.0
max_tokens integer 最大生成 token
max_completion_tokens integer 同上,优先级高于 max_tokens
top_p number 核采样,范围 0.0–1.0
image_config object 图像比例与分辨率配置
top_k integer Top-K 采样,最小值 1

image_config 子字段:

字段 类型 可选值 说明
aspect_ratio enum 1:11:41:83:22:33:44:14:34:55:48:19:1616:921:9 图像宽高比
image_size enum 5121K2K4K 图像分辨率
JSON
{
  "model": "google/gemini-3-pro-image",
  "stream": false,
  "messages": [{
    "role": "user",
    "content": "生成一张日落时分的海边金毛犬照片,电影感光影,写实风格。"
  }],
  "image_config": {"aspect_ratio": "1:1", "image_size": "1K"}
}
JSON
{
  "model": "google/gemini-3-pro-image",
  "stream": false,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "以这张图片为主体,改成日落海边的电影感写实照片,保留金毛犬。"},
      {"type": "image_url", "image_url": {"url": "https://example.com/source.jpg"}}
    ]
  }],
  "image_config": {"aspect_ratio": "1:1", "image_size": "1K"}
}

原厂协议说明:OpenAI Images API

GPT Image 2 使用 OpenAI Chat Completions 兼容的对话接口调用。通过 messages 传入文本提示词和可选的 image_url 图片输入;仅支持非流式调用。

场景 输入 下游接口 路径占位符 {operation}
文生图 无输入图片 Images Generations generations
图生图 含输入图片 Images Edits edits

Gateway 自动检测 messages 中是否存在 type=image 的 content part:有图片时调用 Edits,无图片时调用 Generations。图生图最多 16 张输入图片。

字段 类型 必填 说明
model string 平台 ag_model 配置的模型编码
messages array 消息数组;role=user 消息包含文本提示词和可选图片输入。
stream boolean 固定 false,GPT Image 不支持流式
n integer 生成图片数量
size string 图片尺寸,如 1024x1024
quality string 图片质量,如 high
output_format string 输出格式,如 pngjpg
background string 背景模式,如 opaquetransparent
mask string 蒙版图片(data URL 或 URL),用于局部编辑
JSON
{
  "model": "openai/gpt-image-2",
  "stream": false,
  "messages": [{"role": "user", "content": "生成一张雨后街道的赛博朋克夜景插画,霓虹灯倒映在路面,细节丰富。"}],
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png",
  "background": "opaque"
}
JSON
{
  "model": "openai/gpt-image-2",
  "stream": false,
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "将这张图片改造成雨后赛博朋克街景插画,保留主体构图。"},
      {"type": "image_url", "image_url": {"url": "https://example.com/source.jpg"}}
    ]
  }],
  "n": 1,
  "size": "1024x1024",
  "quality": "high",
  "output_format": "png",
  "background": "opaque"
}

生图结果统一使用 chat.completion 风格响应,图片位于 choices[0].message.images[*].image_url.url,为 data:image/...;base64,...。调用方应保存或上传该 Data URL,不应把超长 Base64 完整打印到业务日志。

JSON
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1764574464,
  "model": "google/gemini-3-pro-image",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "",
      "reasoning_content": "**Analyzing...**\n\n...",
      "images": [{
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."},
        "index": 0
      }]
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 1322,
    "total_tokens": 1341
  }
}

Gemini Image 响应特有字段:

字段 说明
choices[].message.reasoning_content 模型思考过程(推理内容)
choices[].message.images[] 生成的图像数组,每项含 typeimage_url.url(data URL)、index

GPT Image 2 响应采用 chat.completion 结构,生成图片位于响应的图片 URL 字段中:

JSON
{
  "id": "image-1764574464",
  "object": "chat.completion",
  "created": 1764574464,
  "model": "openai/gpt-image-2",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "",
      "images": [{
        "type": "image_url",
        "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."},
        "index": 0
      }]
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 500,
    "total_tokens": 600
  }
}

生成图片可从 choices[0].message.images[].image_url.url 读取;返回值可能是可访问 URL 或 data URL,请按实际返回格式使用。

错误响应结构和 HTTP 状态码说明与 4.4 错误响应 保持一致。