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 |
缺失
Authorization或api_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 结构
{ "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 非流式 · 纯文本
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 流式 · 文本 + 图片(多模态)
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
{
"type": "image_url",
"image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }
}
4.2.4 音频(input_audio)
{
"type": "input_audio",
"input_audio": { "data": "<base64>", "format": "wav" }
}
4.3 响应
4.3.1 非流式响应
- HTTP
200 Content-Type: application/json- 单个
chat.completion对象
{
"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
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 风格:
{
"error": {
"message": "missing API key",
"type": "internal_error",
"code": "StreamController.openAiChat.unauthorized"
}
}
HTTP 状态码映射:
| HTTP | 触发场景 |
|---|---|
400 |
请求体为空 / 非法 JSON / 参数缺失(如 参数...为空、is not passed)
|
401 |
缺失 Authorization 或 api_key 无效 |
404 |
模型/路由/API 不存在(模型配置不存在、API not exist) |
429 |
限流 / 配额不足 |
500 |
其它服务端异常 |
流式已开始后的业务错误:以 SSE 错误帧 +
data: [DONE]结束,不会改 HTTP 状态码。
6. OpenAI SDK 接入示例
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
"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);
Modelink AI 生图接口接入说明
Gemini Image 与 GPT Image 2 文生图/图生图。
5. 对话生图
说明:对话生图仅支持非流式请求,请将 stream 设置为
false。
5.1 请求体
5.1.1 通用请求规则
model:已在平台ag_model配置并开通的模型编码。messages:必须包含至少一条role=user的消息,其中含文本提示词。- 图生图输入图使用 OpenAI 标准
image_url;支持公网 URL 或data:image/...;base64,...。 content支持字符串或多模态 content part 数组。- Gemini Image 不支持
audio/video类型输入,仅支持text和image。
5.1.2 Gemini Image
5.1.2.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
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:1、1:4、1:8、3:2、2:3、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9
|
图像宽高比 |
image_size |
enum | 512、1K、2K、4K |
图像分辨率 |
5.2 请求示例
5.2.1 Gemini 文生图示例
{
"model": "google/gemini-3-pro-image",
"stream": false,
"messages": [{
"role": "user",
"content": "生成一张日落时分的海边金毛犬照片,电影感光影,写实风格。"
}],
"image_config": {"aspect_ratio": "1:1", "image_size": "1K"}
}
5.2.2 Gemini 图生图示例
{
"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"}
}
5.1.3 GPT Image 2
原厂协议说明:OpenAI Images API。
GPT Image 2 使用 OpenAI Chat Completions 兼容的对话接口调用。通过 messages 传入文本提示词和可选的
image_url 图片输入;仅支持非流式调用。
4.1 内部路由
| 场景 | 输入 | 下游接口 | 路径占位符 {operation} |
|---|---|---|---|
| 文生图 | 无输入图片 | Images Generations | generations |
| 图生图 | 含输入图片 | Images Edits | edits |
Gateway 自动检测
messages中是否存在type=image的 content part:有图片时调用 Edits,无图片时调用 Generations。图生图最多 16 张输入图片。
5.1.3.1 请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 平台 ag_model 配置的模型编码 |
messages |
array | 是 | 消息数组;role=user 消息包含文本提示词和可选图片输入。 |
stream |
boolean | 否 | 固定 false,GPT Image 不支持流式 |
n |
integer | 否 | 生成图片数量 |
size |
string | 否 | 图片尺寸,如 1024x1024 |
quality |
string | 否 | 图片质量,如 high |
output_format |
string | 否 | 输出格式,如 png、jpg |
background |
string | 否 | 背景模式,如 opaque、transparent |
mask |
string | 否 | 蒙版图片(data URL 或 URL),用于局部编辑 |
5.2.3 GPT 文生图示例
{
"model": "openai/gpt-image-2",
"stream": false,
"messages": [{"role": "user", "content": "生成一张雨后街道的赛博朋克夜景插画,霓虹灯倒映在路面,细节丰富。"}],
"n": 1,
"size": "1024x1024",
"quality": "high",
"output_format": "png",
"background": "opaque"
}
5.2.4 GPT 图生图示例
{
"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"
}
5.3 响应
生图结果统一使用 chat.completion 风格响应,图片位于 choices[0].message.images[*].image_url.url,为
data:image/...;base64,...。调用方应保存或上传该 Data URL,不应把超长 Base64 完整打印到业务日志。
5.3.1 Gemini Image 响应
{
"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[] |
生成的图像数组,每项含 type、image_url.url(data
URL)、index |
5.3.2 GPT Image 2 响应
GPT Image 2 响应采用 chat.completion 结构,生成图片位于响应的图片 URL 字段中:
{
"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,请按实际返回格式使用。
5.4 错误响应
错误响应结构和 HTTP 状态码说明与 4.4 错误响应 保持一致。