API Reference

Getting started, authentication, endpoints, and error codes

Make your first API call

Choose a billing mode and confirm your balance or active quota.
Choose an eligible text model and create the matching API key. Do not assume keys work across billing modes.
Replace YOUR_MODEL_ID in the Bash example. Enter your key privately at the prompt.
Confirm a successful response, then match the request in your usage records. Treat a charged request as a real paid call.

# 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

Troubleshooting

Getting Started

RoboVAI is compatible with OpenAI and Anthropic official clients — just swap the base_url and api_key.

Base URL

https://api.robovai.com

The endpoint below is returned by the current gateway; put it into your client’s base_url / API endpoint field.

OpenAI-compatible clients use https://api.robovai.com/v1; Anthropic-compatible clients (e.g. Claude Code) use https://api.robovai.com.

Create a key in “Dashboard → API Keys”, then put it into your client’s api_key field.

Authentication

Every request carries the API key via an HTTP header:

Authorization: Bearer <api_key>

Key format: subscription keys start with sub_, pay-as-you-go keys start with api_.

Never hardcode keys in frontend code or public repos; reset immediately in the dashboard if leaked.

Endpoints

Anthropic-compatible

https://api.robovai.com

Compatible with the Anthropic Messages API — for Claude Code, official Claude SDKs, etc. Full path: https://api.robovai.com

OpenAI-compatible

Model Modality Endpoints

Endpoints grouped by input/output modality. Text chat is sync/stream; image generation returns a URL synchronously; video generation is async (submit then poll). All request bodies are forwarded to the upstream provider — only model is required; other fields follow the corresponding model spec.

Async endpoint: submit to get a task_id, then poll for the result.

Text Chat

Sync or streaming text chat, compatible with both OpenAI and Anthropic protocols.

POSTChat Completions

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

OpenAI-compatible, supports streaming. Full path: https://api.robovai.com/v1/chat/completions

POSTMessages (Anthropic)

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

Anthropic-compatible, for Claude Code etc. Full path: https://api.robovai.com/v1/messages

POSTResponses

Error Codes

Status	Meaning	Suggestion
400 Bad Request	Invalid request parameters	Check the body, model name, and parameter format.
401 Unauthorized	Missing or invalid key	Ensure the Authorization header carries a valid API key.
402 Payment Required	Insufficient balance or quota exhausted	Top up in the dashboard or switch keys.
403 Forbidden	No access to this model	Confirm your key’s plan includes the target model.
404 Not Found	Model or endpoint not found	Verify the model ID and endpoint path.
429 Too Many Requests	Rate limited	Reduce request frequency or retry later.

Field	Type	Required	Description
model	string	Yes	Model ID.
messages	array	Yes	Conversation message array, with role and content.
stream	boolean	No	Stream the response, default false.
temperature	number	No	Sampling temperature, 0–2, default 1.
max_tokens	integer	No	Maximum tokens to generate.
tools

Request example

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

Response example

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

Image Generation

Returns the generated image URL synchronously (OpenAI gpt-image via /v1; Volcengine Doubao Seedream etc. via /v1/multimodal; Midjourney via /v1/mj).

POSTText-to-Image (OpenAI)

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

OpenAI gpt-image and similar models. Full path: https://api.robovai.com/v1/images/generations

POSTImage Edit (OpenAI)

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

Image editing from a reference image. Full path: https://api.robovai.com/v1/images/edits

POSTText-to-Image (Multimodal)

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

Volcengine Doubao Seedream and similar multimodal models. Full path: https://api.robovai.com/v1/multimodal/images/generations

Video Generation

Async interface: submit a task to get a task_id, then poll until it succeeds and returns result_url.

POSTSubmit Generation Task

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

Submit a video generation, returns task_id. Full path: https://api.robovai.com/v1/multimodal/videos/generations

GETPoll Task Status

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

Query task status; returns result_url on success. Full path: https://api.robovai.com/v1/multimodal/videos/tasks/:task_id

GETGet Video Content

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

Content proxy for succeeded tasks; returns the video file directly (succeeded tasks only). Full path: https://api.robovai.com/v1/multimodal/videos/tasks/:task_id/content

Audio

OpenAI-compatible audio endpoints: text-to-speech, transcription, translation.

POSTText-to-Speech

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

TTS; takes text, returns audio. Full path: https://api.robovai.com/v1/audio/speech

POSTTranscription

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

Audio to text. Full path: https://api.robovai.com/v1/audio/transcriptions

POSTTranslation

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

Translate audio into text in the target language. Full path: https://api.robovai.com/v1/audio/translations

Field

Field	Type	Required	Description
model	string	Yes	Model ID (e.g. gpt-image, Seedream series).
prompt	string	Yes	Image description prompt.
n	integer	No	Number of images, default 1.
size	string	No	Image size, e.g. 1024x1024.
quality	string	No	Quality (OpenAI): standard/hd.
response_format

Request example

{
  "model": "<model_id>",
  "prompt": "a cat on the moon",
  "size": "1024x1024",
  "n": 1
}

Response example

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

Field	Type	Required	Description
model	string	Yes	Model ID (e.g. Seedance series).
prompt	string	Yes	Video description prompt.
duration	number	No	Video length in seconds, e.g. 5.
resolution	string	No	Resolution, e.g. 720p, 1080p.
ratio	string	No	Aspect ratio, e.g. 16:9, 9:16.
fps

Request example

{
  "model": "<model_id>",
  "prompt": "sunset over the waves"
}

Response example

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

Request example

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

Response example

(binary audio stream, Content-Type: audio/mpeg)

model	string	Yes	Model ID (e.g. tts-1).
input	string	Yes	Text to synthesize.
voice	string	Yes	Voice, e.g. alloy, echo, nova.
response_format	string	No	Audio format: mp3/opus/aac/flac, default mp3.
speed	number	No	Speed, 0.25–4, default 1.