Tham chiếu API

Bắt đầu, xác thực, endpoint và mã lỗi

Lệnh gọi API đầu tiên

Chọn cách tính phí và kiểm tra số dư hoặc hạn mức đang hoạt động.
Chọn mô hình văn bản được phép và tạo khóa tương ứng. Không mặc định dùng chung khóa giữa các cách tính phí.
Thay YOUR_MODEL_ID trong ví dụ Bash và nhập khóa riêng tư tại lời nhắc.
Kiểm tra phản hồi thành công và đối chiếu lịch sử sử dụng. Lệnh gọi thực tế có thể phát sinh phí.

# 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

Xử lý lỗi

401: kiểm tra khóa và điểm cuối; 402: số dư hoặc hạn mức; 429: giảm đồng thời và làm theo hướng dẫn thử lại; 503: kiểm tra nhà cung cấp hoặc liên hệ hỗ trợ.

Bắt đầu

RoboVAI tương thích với client chính thức của OpenAI và Anthropic — chỉ cần thay base_url và api_key.

Base URL

https://api.robovai.com

Endpoint dưới đây được trả về bởi gateway hiện tại; hãy điền vào trường base_url / endpoint API của client.

Client tương thích OpenAI dùng https://api.robovai.com/v1; client tương thích Anthropic (vd. Claude Code) dùng https://api.robovai.com.

Tạo khóa trong “Bảng điều khiển → Khóa API”, sau đó điền vào trường api_key của client.

Xác thực

Mọi yêu cầu đều gửi khóa API qua HTTP header:

Authorization: Bearer <api_key>

Định dạng khóa: khóa đăng ký bắt đầu bằng sub_, khóa trả theo lượng dùng bắt đầu bằng api_.

Không hardcode khóa trong code frontend hay repo công khai; đặt lại ngay trong bảng điều khiển nếu bị lộ.

Danh sách endpoint

Tương thích Anthropic

https://api.robovai.com

Tương thích API Messages của Anthropic — cho Claude Code, SDK chính thức Claude, v.v. Đường dẫn đầy đủ: https://api.robovai.com

Tương thích OpenAI

Endpoint theo modalitas

Các endpoint được nhóm theo modalitas đầu vào/đầu ra. Chat văn bản là đồng bộ/streaming; tạo ảnh trả về URL đồng bộ; tạo video là bất đồng bộ (gửi rồi polling). Mọi body request đều được chuyển tiếp tới provider thượng nguồn — chỉ model là bắt buộc; các trường khác tuân theo spec của model tương ứng.

Endpoint bất đồng bộ: gửi để lấy task_id, rồi polling kết quả.

Chat văn bản

Chat văn bản đồng bộ hoặc streaming, tương thích cả hai giao thức OpenAI và Anthropic.

POSTChat Completions

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

Tương thích OpenAI, hỗ trợ streaming. Đường dẫn đầy đủ: https://api.robovai.com/v1/chat/completions

POSTMessages (Anthropic)

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

Tương thích Anthropic, cho Claude Code v.v. Đường dẫn đầy đủ: https://api.robovai.com/v1/messages

POSTResponses

Mã lỗi

Trạng thái	Ý nghĩa	Gợi ý
400 Bad Request	Tham số yêu cầu sai	Kiểm tra body, tên model và định dạng tham số.
401 Unauthorized	Thiếu hoặc sai khóa	Đảm bảo header Authorization mang khóa API hợp lệ.
402 Payment Required	Số dư không đủ hoặc hết hạn mức	Nạp tiền trong bảng điều khiển hoặc đổi khóa.
403 Forbidden	Không có quyền truy cập model	Xác nhận gói của khóa có chứa model mục tiêu.
404 Not Found	Không tìm thấy model hoặc endpoint	Kiểm tra ID model và đường dẫn endpoint.
429 Too Many Requests	Giới hạn tần suất	Giảm tần suất yêu cầu hoặc thử lại sau.

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID model.
messages	array	Có	Mảng tin nhắn với role và content.
stream	boolean	Không	Streaming response, mặc định false.
temperature	number	Không	Nhiệt độ sampling, 0–2, mặc định 1.
max_tokens	integer	Không	Số token tối đa được tạo.
tools

Ví dụ request

{
  "model": "<model_id>",
  "messages": [
    { "role": "user", "content": "Xin chào" }
  ],
  "stream": false
}

Ví dụ response

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

Tạo ảnh

Trả về URL ảnh đã tạo đồng bộ (OpenAI gpt-image qua /v1; Volcengine Doubao Seedream v.v. qua /v1/multimodal; Midjourney qua /v1/mj).

POSTVăn bản sang ảnh (OpenAI)

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

OpenAI gpt-image và các model tương tự. Đường dẫn đầy đủ: https://api.robovai.com/v1/images/generations

POSTChỉnh sửa ảnh (OpenAI)

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

Chỉnh sửa ảnh từ ảnh tham chiếu. Đường dẫn đầy đủ: https://api.robovai.com/v1/images/edits

POSTVăn bản sang ảnh (multimodal)

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

Volcengine Doubao Seedream và các model multimodal tương tự. Đường dẫn đầy đủ: https://api.robovai.com/v1/multimodal/images/generations

Tạo video

Giao diện bất đồng bộ: gửi tác vụ để lấy task_id, rồi polling cho đến khi thành công và trả về result_url.

POSTGửi tác vụ tạo

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

Gửi tạo video, trả về task_id. Đường dẫn đầy đủ: https://api.robovai.com/v1/multimodal/videos/generations

GETPolling trạng thái tác vụ

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

Truy vấn trạng thái tác vụ; trả về result_url khi thành công. Đường dẫn đầy đủ: https://api.robovai.com/v1/multimodal/videos/tasks/:task_id

GETLấy nội dung video

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

Proxy nội dung cho tác vụ thành công; trả trực tiếp tệp video (chỉ khi status=succeeded). Đường dẫn đầy đủ: https://api.robovai.com/v1/multimodal/videos/tasks/:task_id/content

Âm thanh

Endpoint âm thanh tương thích OpenAI: văn bản sang giọng nói, chuyển ngữ, dịch.

POSTVăn bản sang giọng nói

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

TTS; nhận văn bản, trả về âm thanh. Đường dẫn đầy đủ: https://api.robovai.com/v1/audio/speech

POSTChuyển ngữ

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

Âm thanh sang văn bản. Đường dẫn đầy đủ: https://api.robovai.com/v1/audio/transcriptions

POSTDịch

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

Dịch âm thanh sang văn bản ngôn ngữ đích. Đường dẫn đầy đủ: https://api.robovai.com/v1/audio/translations

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID model (vd. gpt-image, dòng Seedream).
prompt	string	Có	Prompt mô tả ảnh.
n	integer	Không	Số ảnh, mặc định 1.
size	string	Không	Kích thước ảnh, vd. 1024x1024.
quality	string	Không	Chất lượng (OpenAI): standard/hd.
response_format

Ví dụ request

{
  "model": "<model_id>",
  "prompt": "mèo trên mặt trăng",
  "size": "1024x1024",
  "n": 1
}

Ví dụ response

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

Trường	Kiểu	Bắt buộc	Mô tả
model	string	Có	ID model (vd. dòng Seedance).
prompt	string	Có	Prompt mô tả video.
duration	number	Không	Độ dài video (giây), vd. 5.
resolution	string	Không	Độ phân giải, vd. 720p, 1080p.
ratio	string	Không	Tỉ lệ khung hình, vd. 16:9, 9:16.
fps

Ví dụ request

{
  "model": "<model_id>",
  "prompt": "hoàng hôn trên sóng"
}

Ví dụ response

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

Ví dụ request

{
  "model": "tts-1",
  "input": "Xin chào",
  "voice": "alloy"
}

Ví dụ response

(luồng âm thanh nhị phân, Content-Type: audio/mpeg)

model	string	Có	ID model (vd. tts-1).
input	string	Có	Văn bản cần tổng hợp.
voice	string	Có	Giọng đọc, vd. alloy, echo, nova.
response_format	string	Không	Định dạng âm thanh: mp3/opus/aac/flac, mặc định mp3.
speed	number	Không	Tốc độ, 0.25–4, mặc định 1.