OpenAI 兼容接口

平台兼容 OpenAI 的模型调用方式。已有 OpenAI SDK 代码通常只需修改 base_url 和 api_key；请求参数、非流式响应和 SSE 流式事件继续使用 OpenAI 协议结构。

快速接入

模型服务 Base URL：

https://runtime-api.invalid/v1/compatible-mode

鉴权请求头：

Authorization: Bearer sk_your_api_key

API Key 已绑定工作空间，不需要传入其他工作空间请求头。

Python SDK

安装官方 SDK：

pip install openai

设置环境变量，其中 AIADP_MODEL_ID 必须使用模型列表返回的模型 ID：

export AIADP_MODEL_BASE_URL="https://runtime-api.invalid/v1/compatible-mode"
export AIADP_API_KEY="sk_your_api_key"
export AIADP_MODEL_ID="your-model-id"

发起对话：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIADP_API_KEY"],
    base_url=os.environ["AIADP_MODEL_BASE_URL"],
)

completion = client.chat.completions.create(
    model=os.environ["AIADP_MODEL_ID"],
    messages=[
        {"role": "user", "content": "你好，请用一句话介绍你自己。"},
    ],
)

print(completion.choices[0].message.content)

cURL

先查看可用模型：

curl 'https://runtime-api.invalid/v1/compatible-mode/models' \
  -H 'Authorization: Bearer sk_your_api_key'

选择一个包含 chat_completions 能力的模型 ID 后发起对话：

curl -X POST 'https://runtime-api.invalid/v1/compatible-mode/chat/completions' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你自己。"}
    ]
  }'

支持的接口

下列路径均相对于 https://runtime-api.invalid/v1/compatible-mode：

方法	路径	能力	说明
GET	/models	模型列表	返回当前 API Key 可访问的模型及其能力
GET	/models/{model}	模型详情	获取指定公开模型 ID；ID 可以包含 /
POST	/chat/completions	Chat Completions	支持非流式和流式响应，取决于模型能力
POST	/responses	Responses	支持非流式和流式响应，取决于模型能力
POST	/embeddings	Embeddings	创建文本或数组输入的向量表示
POST	/rerank	Rerank	Cohere 风格的重排序扩展，不属于 OpenAI 官方 SDK 资源
POST	/audio/transcriptions	Audio Transcriptions	使用 multipart/form-data 上传音频并转写
POST	/audio/speech	Audio Speech	将文本转换为语音，响应格式由请求和上游模型决定

除模型发现和 Rerank 扩展外，各能力的请求与响应字段遵循 OpenAI 对应协议。接入方无需使用平台私有的响应包装结构。

模型名称

调用 GET /models 获取公开模型 ID 与能力：

{
  "object": "list",
  "data": [
    {
      "id": "provider/model-name",
      "object": "model",
      "created": 1786723200,
      "owned_by": "provider",
      "capabilities": [
        "chat_completions",
        "streaming"
      ]
    }
  ]
}

请求前应检查目标能力：

capabilities 值	对应接口或特性
chat_completions	/chat/completions
responses	/responses
embeddings	/embeddings
rerank	/rerank
audio.transcriptions	/audio/transcriptions
audio.speech	/audio/speech
streaming	Chat Completions 或 Responses 流式响应

TIP

模型列表可能额外返回 capability_details，用于描述某项能力的实现细节。接入方应以 capabilities 判断接口是否可调用，不要根据厂商或模型名称推断能力。

流式响应

Chat Completions 和 Responses 支持 stream: true。只有同时包含对应接口能力和 streaming 能力的模型可以使用流式响应。

stream = client.chat.completions.create(
    model=os.environ["AIADP_MODEL_ID"],
    messages=[{"role": "user", "content": "介绍一下成都。"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

其他接口不接受流式模式。请求的模型不支持流式响应时，服务返回 unsupported_capability。

Rerank 扩展

Rerank 使用 Cohere 风格的 JSON 请求，通过普通 HTTP 客户端调用：

curl -X POST 'https://runtime-api.invalid/v1/compatible-mode/rerank' \
  -H 'Authorization: Bearer sk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "your-rerank-model-id",
    "query": "什么是向量检索？",
    "documents": [
      "向量检索通过计算向量相似度召回内容。",
      "关系型数据库使用表组织结构化数据。"
    ]
  }'

错误响应

请求进入模型服务后，错误使用 OpenAI 兼容结构：

{
  "error": {
    "message": "model 字段不能为空",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_model"
  }
}

param 只在错误关联到具体参数时返回。

HTTP 状态码	常见 code	说明
400	invalid_request、invalid_model、unsupported_capability	请求格式、模型字段或模型能力不符合要求
401	—	API Key 缺失、格式错误或不可用；由网关直接返回
404	model_not_found	模型不存在或未向当前 API Key 开放
413	request_too_large	请求体超过大小限制
429	以上游响应为准	上游模型限流
502	invalid_provider_response	上游模型返回无效响应
504	request_timeout	模型请求处理超时

接入说明

• 所有 JSON 接口都要求请求体是单个 JSON 对象，并且 model 必须是非空字符串且只能出现一次。
• JSON 请求体最大为 20 MiB；语音转写的 multipart 请求体最大为 30 MiB。
• /audio/transcriptions 的表单必须包含且只能包含一个非空 model 字段。
• OpenAI-Beta 与 Idempotency-Key 会按需转发给上游模型；平台 API Key 不会转发。
• 成功响应的状态码、响应体与常用协议头由上游模型透传。
• OpenAI SDK 初始化参数及调用方式可参考官方 Python SDK。