API 接入

中转站开发者文档

从创建中转站 API Key 到查询模型目录。本页是接口预览，不会调用 API，也不会读取或保存你的密钥。

接入前准备

取得中转站 API Key。 待控制台开放后，在「API 密钥」里按应用创建。完整值仅在创建时显示，请妥善保存。
配置 API 地址。 规划 Base URL 为 https://api.yyangai.cn/v1，控制台和文档使用 ai.yyangai.cn。如果客户端已配置 Base URL，不要在模型路径前再加一次 /v1。
先查模型目录。 请求使用 Authorization: Bearer <RELAY_API_KEY>。商城凭证、网站登录会话和上游供应商密钥都不能替代中转站 API Key。

GET

读取当前 Key 可见的模型目录，不触发推理。公网开放前，请勿把这条示例当成服务已开放的证明。

curl 'https://api.yyangai.cn/v1/models' \
  -H "Authorization: Bearer $RELAY_API_KEY"

M13 关闭测试上游时，鉴权成功的返回示例：

{"object":"list","data":[]}

data: [] 表示目录当前为空。没有模型 ID 时，不要猜型号或改用测试型号。

POST

以下为格式说明，不是可用模型示例。请求必须使用 Content-Type: application/json，并把 model 替换为目录返回且已开放的 ID。M13 冻结包中，有效 Key 提交此接口会收到 503 upstream_disabled。

{
  "model": "MODEL_ID_FROM_CATALOG",
  "messages": [{"role": "user", "content": "你好"}],
  "max_completion_tokens": 64,
  "stream": false
}

messages: 文字消息数组；测试合约接受 system、user、assistant，每条 content 是非空字符串。
max_completion_tokens: 或使用 max_tokens，只能二选一。测试合约输出上限为 1–4096，未指定默认 256；未知字段会被拒绝。
stream: 测试合约支持 SSE；只有 stream: true 时可传 stream_options: {"include_usage": true}。成功结束有 data: [DONE]；中途断流不能视为成功。

非流式成功响应格式使用 choices[0].message.content 和 usage。不代表实际模型质量、计费价格或公网上线。

读取响应的 error.code；服务已登记请求时，也可能返回 X-Request-ID。对 POST 请求，可设置一次生成的 Idempotency-Key，用于定位同一逻辑请求。

候选接口的常见响应
状态码	含义与处理
`400 / 415`	检查 JSON、请求头和受支持字段。
`401`	核对中转站 API Key 是否有效，避免误用登录会话或商城密钥。
`404`	检查接口地址、路径和模型目录；不要猜测型号。
`409 duplicate_request`	相同请求标识已有记录。回到用量记录核对，不要换标识重新发起同一请求。
`503 upstream_disabled`	模型调用未启用；停止调用，不要自动重试或尝试付款。

断线或其他结果不明时保留原请求标识，先查控制台用量。收到 409 不等于已拿到模型结果，也不证明已收费。

把 Key 保存在服务端环境或秘密管理器，不写进浏览器代码、公开仓库、截图或日志。密钥泄露时，在控制台停用并更换。这里没有输入框、试运行按钮或真实凭据。