API 接口

接入指南、鉴权方式、端点列表与错误码

完成首次 API 调用

选择计费方式，确认余额或生效的配额。
选择有权限的文本模型，创建对应 API Key。不要假设不同计费方式可以共用 Key。
替换 Bash 示例中的 YOUR_MODEL_ID，在提示符中私密输入 Key。
确认响应成功，再到用量记录核对请求。实际调用可能产生费用。

# Bash: replace YOUR_MODEL_ID with an eligible text model from the catalog.
read -r -s -p 'API key: ' ROBOVAI_API_KEY; printf '\n'
curl --fail-with-body 'https://api.robovai.com/v1/chat/completions' \
  -H "Authorization: Bearer ${ROBOVAI_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}],"max_tokens":32}'
unset ROBOVAI_API_KEY

遇到错误

401：核对 Key 与端点；402：核对余额或配额；429：降低并发并遵循重试提示；503：检查上游状态或联系支持。

接入指南

RoboVAI 兼容 OpenAI 与 Anthropic 官方客户端，只需替换 base_url 与 api_key 即可接入。

Base URL

鉴权方式

所有请求均通过 HTTP Header 携带 API 密钥：

Authorization: Bearer <api_key>

密钥格式：订阅密钥以 sub_ 开头，按量密钥以 api_ 开头。

请勿将密钥硬编码到前端代码或公开仓库中；泄露后请在控制台立即重置。

端点列表

Anthropic 兼容

https://api.robovai.com

兼容 Anthropic Messages API，用于 Claude Code、Claude 官方 SDK 等。完整路径：https://api.robovai.com

OpenAI 兼容

/v1

https://api.robovai.com/v1

兼容 OpenAI Chat/Completions API，用于 ChatBox、OpenCat 等客户端。完整路径：https://api.robovai.com/v1

模型模态接口

按输入/输出模态划分的端点说明。文字对话走同步/流式接口；图片生成同步返回 URL；视频生成异步提交后轮询。所有端点请求体透传至上游供应商，仅 model 为必填，其余字段遵循对应模型规范。

异步端点：先提交获取 task_id，再轮询查询结果。

文字对话

同步或流式文本对话，兼容 OpenAI 与 Anthropic 两套协议。

POST对话补全

https://api.robovai.com/v1/chat/completions

OpenAI 兼容，支持 stream 流式。完整路径：https://api.robovai.com/v1/chat/completions

POST消息（Anthropic）

https://api.robovai.com/v1/messages

Anthropic 兼容，用于 Claude Code 等。完整路径：https://api.robovai.com/v1/messages

POSTResponses

https://api.robovai.com/v1/responses

OpenAI Responses API（含 WebSocket）。完整路径：https://api.robovai.com/v1/responses

错误码

状态码	含义	处理建议
400 Bad Request	请求参数错误	检查请求体、模型名与参数格式。
401 Unauthorized	密钥无效或未提供	确认 Authorization Header 携带了正确的 API 密钥。
402 Payment Required	余额不足或订阅额度已耗尽	前往控制台充值或更换密钥。
403 Forbidden	无权访问该模型	确认当前密钥的套餐包含目标模型。
404 Not Found	模型或端点不存在	核对模型 ID 与端点路径。
429 Too Many Requests	触发限流	降低请求频率，或稍后重试。
500 Internal Server Error	服务端异常	稍后重试；持续报错请联系支持。

字段	类型	必填	说明
model	string	是	模型 ID。
messages	array	是	对话消息数组，含 role 与 content。
stream	boolean	否	是否流式返回，默认 false。
temperature	number	否	采样温度，0~2，默认 1。
max_tokens	integer	否	最大生成 token 数。
tools	array

请求示例

{
  "model": "<model_id>",
  "messages": [
    { "role": "user", "content": "你好" }
  ],
  "stream": false
}

响应示例

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "你好！" }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 4, "completion_tokens": 3 }
}

图片生成

同步返回生成图片的 URL（OpenAI gpt-image 走 /v1，火山豆包 Seedream 等走 /v1/multimodal，Midjourney 走 /v1/mj）。

POST文生图（OpenAI）

https://api.robovai.com/v1/images/generations

OpenAI gpt-image 等模型。完整路径：https://api.robovai.com/v1/images/generations

POST图片编辑（OpenAI）

https://api.robovai.com/v1/images/edits

基于参考图的图片编辑。完整路径：https://api.robovai.com/v1/images/edits

POST文生图（多模态）

https://api.robovai.com/v1/multimodal/images/generations

火山豆包 Seedream 等多模态模型。完整路径：https://api.robovai.com/v1/multimodal/images/generations

POST

视频生成

异步接口：提交任务返回 task_id，轮询查询直到成功拿到 result_url。

POST提交生成任务

https://api.robovai.com/v1/multimodal/videos/generations

提交视频生成，返回 task_id。完整路径：https://api.robovai.com/v1/multimodal/videos/generations

GET轮询任务状态

https://api.robovai.com/v1/multimodal/videos/tasks/:task_id

查询任务状态，成功后返回 result_url。完整路径：https://api.robovai.com/v1/multimodal/videos/tasks/:task_id

GET获取视频内容

https://api.robovai.com/v1/multimodal/videos/tasks/:task_id/content

成功任务的内容代理，直接返回视频文件（仅 status=succeeded 可用）。完整路径：https://api.robovai.com/v1/multimodal/videos/tasks/:task_id/content

响应示例

{
  "task_id": "task_abc123",
  "status": "succeeded",
  "result_url": "https://.../video.mp4",
  "expires_at": "2026-08-09T00:00:00Z"
}

音频

OpenAI 兼容音频端点：文本转语音、语音转写、翻译。

POST文本转语音

https://api.robovai.com/v1/audio/speech

TTS，输入文本返回音频。完整路径：https://api.robovai.com/v1/audio/speech

POST语音转写

https://api.robovai.com/v1/audio/transcriptions

音频转文字。完整路径：https://api.robovai.com/v1/audio/transcriptions

POST语音翻译

https://api.robovai.com/v1/audio/translations

音频翻译为目标语言文字。完整路径：https://api.robovai.com/v1/audio/translations

字段	类型	必填	说明

字段	类型	必填	说明
model	string	是	模型 ID（如 gpt-image、Seedream 系列）。
prompt	string	是	图像描述提示词。
n	integer	否	生成数量，默认 1。
size	string	否	图像尺寸，如 1024x1024。
quality	string	否	质量（OpenAI）：standard/hd。
response_format	string

请求示例

{
  "model": "<model_id>",
  "prompt": "一只在月球上的猫",
  "size": "1024x1024",
  "n": 1
}

响应示例

{
  "created": 1700000000,
  "data": [
    { "url": "https://.../image.png" }
  ]
}

请求示例

{
  "model": "<model_id>",
  "prompt": "夕阳下的海浪"
}

响应示例

{
  "task_id": "task_abc123",
  "status": "pending",
  "upstream_id": "upstream_xyz"
}

请求示例

{
  "model": "tts-1",
  "input": "你好",
  "voice": "alloy"
}

响应示例

（二进制音频流，Content-Type: audio/mpeg）

model	string	是	模型 ID（如 Seedance 系列）。
prompt	string	是	视频描述提示词。
duration	number	否	视频时长（秒），如 5。
resolution	string	否	分辨率，如 720p、1080p。
ratio	string	否	画幅比例，如 16:9、9:16。
fps	number	否	帧率，如 24、30。

model	string	是	模型 ID（如 tts-1）。
input	string	是	要合成的文本。
voice	string	是	音色，如 alloy、echo、nova。
response_format	string	否	音频格式：mp3/opus/aac/flac，默认 mp3。
speed	number	否	语速，0.25~4，默认 1。