API 参考
API 概述与认证
本篇给出调用 Yomi API 的基础约定：服务地址、认证方式、端点一览与通用错误码。各接口的详细参数与示例见对应分篇。
基础约定
- API 地址: https://api.yomiapi.com,OpenAI 兼容路径统一以
/v1为前缀 - 认证方式: HTTP Header
Authorization: Bearer <API密钥> - 请求格式:
Content-Type: application/json,UTF-8 编码 - 兼容性: 接口与 OpenAI 格式兼容，官方 SDK 将
base_url指向https://api.yomiapi.com/v1即可直接使用
三种协议入口按需选择，点击切换查看对应 Base URL:
OpenAI SDK 与所有兼容工具统一使用:
https://api.yomiapi.com/v1Anthropic SDK 原生格式，地址不带 /v1(接口为 /v1/messages):
https://api.yomiapi.comGemini 原生 generateContent 格式:
https://api.yomiapi.com/v1beta/models/{model}:generateContent认证方式
在控制台「秘钥管理」创建密钥后，每个请求都在请求头中携带该密钥:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/jsonAPI 密钥等同于账户余额的使用权，请通过环境变量或密钥管理服务保存，不要写入前端代码、客户端安装包或公开仓库。密钥泄露时请立即在「秘钥管理」中删除并重建。
端点一览
| 端点 | 说明 |
|---|---|
POST /v1/chat/completions | 对话补全，支持流式输出，最常用 |
POST /v1/completions | 旧版文本补全，兼容保留 |
POST /v1/messages | Anthropic Claude 原生格式 |
POST /v1/responses | OpenAI Responses 格式，另有 /v1/responses/compact |
POST /v1/images/generations | 图像生成 |
POST /v1/images/edits | 图像编辑 |
POST /v1/video/generations | 视频生成(异步任务),另有 OpenAI 兼容的 POST /v1/videos,详见媒体生成章「Veo 4 视频生成」 |
POST /v1/embeddings | 嵌入向量 |
POST /v1/audio/transcriptions | 语音转写 |
POST /v1/audio/translations | 语音翻译 |
POST /v1/audio/speech | 语音合成 |
POST /v1/moderations | 文本审核 |
POST /v1/rerank | 重排序 |
GET /v1/models | 模型列表,/v1/models/{model} 查询单个模型 |
GET /v1/realtime | WebSocket 实时接口 |
原生格式入口
除 OpenAI 兼容格式外，平台还提供厂商原生格式:Claude 系列可走 POST /v1/messages(Anthropic Messages 格式);Gemini 系列可走原生路径:
POST https://api.yomiapi.com/v1beta/models/{model}:generateContent不支持的接口
以下 OpenAI 接口平台未开放:/v1/images/variations(图像变体)、/v1/files(文件管理)、/v1/fine-tunes(微调)。即平台不支持微调与 Files 管理。
快速验证
用下面的请求验证密钥与网络连通性，能收到回复即表示接入成功:
curl https://api.yomiapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{"role": "user", "content": "你好,请介绍一下自己。"}
]
}'在请求体中加入 "stream": true 可开启流式输出，详细说明见「对话补全」一篇。
通用错误码
| 错误码 | 含义 | 处理建议 |
|---|---|---|
| 400 | 请求参数错误 | 检查请求体格式与参数取值 |
| 401 | API 密钥无效或未携带 | 检查 Authorization 头与密钥状态 |
| 403 | 无权访问或额度不足 | 检查密钥的分组与可用模型配置;确认账户余额与订阅状态 |
| 404 | 模型或路径不存在 | 核对模型 id 与请求路径 |
| 413 | 请求体过大 | 检查上传文件大小（图片/视频等），压缩后重试 |
| 429 | 触发限流 | 降低请求频率并采用指数退避重试 |
| 500 | 服务器内部错误 | 稍后重试 |
| 502 | 上游服务错误 | 稍后重试，或临时切换其他模型 |
| 503 | 服务暂时不可用 | 稍后重试，或临时切换其他模型 |
使用建议
- 密钥管理: 用环境变量注入密钥，按项目或环境拆分多把密钥，便于独立控制与吊销。
- 错误重试: 对 429 与 5xx 错误实现指数退避重试;各模型的速率限制以模型广场线路信息为准。
- 成本控制: 合理设置
max_tokens,避免不必要的长输出。 - 体验优化: 面向终端用户的长文本生成建议开启流式输出。