OpenAI 兼容范围
对话模型可通过 OpenAI SDK 的 chat.completions.create 调用。Gateway 仅覆盖下列接口,支持的参数取决于所选模型。完整示例见 首次调用。
地址与认证
| 配置 | 值 |
|---|---|
SDK base_url | https://gw.zeroseal.cn/v1 |
| 对话请求地址 | https://gw.zeroseal.cn/v1/chat/completions |
| 认证头 | Authorization: Bearer <API key> |
| POST 请求格式 | Content-Type: application/json |
使用国内站控制台创建的密钥。base_url 填到 /v1,调用方法会追加接口路径。
从服务端或本地程序发起请求;对话接口未开放浏览器跨域调用。以上配置不执行客户端 TEE 验证。
接口范围
| 方法与路径 | 范围 |
|---|---|
GET /v1/models | 公开模型列表,无需密钥;默认只列对话模型 |
GET /v1/catalog/models | zeroseal 扩展目录,无需密钥;包含类别、价格和上下文等信息 |
POST /v1/chat/completions | 对话,支持普通响应和 SSE 流式响应 |
POST /v1/images/generations | 图片生成,参数按所选模型支持范围填写 |
POST /v1/audio/speech | 语音合成,返回音频字节;支持 input、voice、response_format、speed,音色和格式取决于模型 |
POST /v1/videos | 提交视频任务,使用模型对应的 JSON 参数 |
GET /v1/videos/{id} | 查询视频任务,使用任务所属账号的有效密钥 |
除两个目录接口外,上表接口均需 Bearer 认证。/v1/models 可用 ?surface=chat、image、speech、video 或 all 筛选。
图片、语音、视频示例见 多模态接口。视频的请求和响应字段按模型区分,不能直接套用 OpenAI 视频 SDK 的数据结构。
当前未提供:
- Responses、Embeddings、旧版 Completions(
/v1/completions)。 - Files、Batches、Assistants、Threads、Realtime。
- 语音转写、翻译接口,
/v1/images/edits、/v1/images/variations。 GET /v1/models/{id},对话记录的查询、更新和删除接口。
迁移已有程序时,确认使用 chat.completions.create,调用 responses.create 会返回 404。
对话参数
| 参数 | 用法 |
|---|---|
model | 使用控制台展示的模型 ID,并选择「对话」类别 |
messages | 发送本轮问题和需要保留的历史消息;角色、图片等内容类型取决于模型支持情况 |
max_completion_tokens/max_tokens | 按模型要求选一种。Gateway 不互相转换这两个参数;预扣优先读取正数 max_completion_tokens |
stream | false 返回完整 JSON;true 返回 SSE |
temperature、top_p、tools、tool_choice、response_format 等 | 传给上游模型,Gateway 不补齐模型缺失的能力 |
推理开关、JSON Schema、工具调用、视觉输入等,需确认所选模型是否支持。更换模型时,先用最小文本请求确认可用,再加入扩展参数。
max_completion_tokens 在 OpenAI 规范中包含思考与可见回答;各模型对输出上限的支持和含义可能不同。字段定义可查 OpenAI Chat Completions 文档。
对话响应保留上游字段,返回的 model 可能与请求中的 ID 不同。错误正文可能使用 message 或 error.message,处理方式见 错误排查。
流式与工具调用
流式请求设置 stream: true,cURL 加 -N 关闭输出缓冲。请求示例、事件解析和断流处理见 流式响应。
支持工具调用的模型可接收 tools 和 tool_choice。收到 tool_calls 后,由你的程序校验参数、执行工具,并将结果作为 role: "tool" 消息,连同历史消息再次发送;Gateway 不执行工具。流式工具参数可能分块返回,收齐后再解析。
断开连接或超时后仍可能产生费用,重试前先查看 消费记录。