API 참조

시작하기, 인증, 엔드포인트, 오류 코드

첫 API 호출

요금 방식을 선택하고 잔액 또는 활성 할당량을 확인하세요.
사용 가능한 텍스트 모델과 해당 API 키를 선택하세요. 요금 방식 간 키 공유를 가정하지 마세요.
Bash 예제의 YOUR_MODEL_ID를 바꾸고 프롬프트에서 키를 비공개로 입력하세요.
정상 응답을 확인하고 사용 기록과 대조하세요. 실제 호출에는 요금이 발생할 수 있습니다.

# 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: 키와 엔드포인트 확인. 402: 잔액과 할당량 확인. 429: 동시 요청을 줄이고 재시도 안내 준수. 503: 업스트림 상태 확인 또는 지원 문의.

시작하기

RoboVAI는 OpenAI 및 Anthropic 공식 클라이언트와 호환됩니다. base_url과 api_key만 교체하면 됩니다.

인증

모든 요청은 HTTP 헤더로 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 프로토콜 모두 호환.

POSTChat Completions

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

OpenAI 호환, 스트리밍 지원. 전체 경로: https://api.robovai.com/v1/chat/completions

POSTMessages (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 헤더에 올바른 API 키를 넣으세요.
402 Payment Required	잔액 부족 또는 한도 소진	대시보드에서 충전하거나 키를 교체하세요.
403 Forbidden	모델 접근 권한 없음	키의 요금제에 대상 모델이 포함되어 있는지 확인하세요.
404 Not Found	모델 또는 엔드포인트 없음	모델 ID와 엔드포인트 경로를 확인하세요.
429 Too Many Requests	요청 제한	요청 빈도를 낮추거나 나중에 재시도하세요.
500 Internal Server Error	서버 오류

POSTEmbeddings

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

텍스트 벡터화. 전체 경로: https://api.robovai.com/v1/embeddings

필드	타입	필수	설명
model	string	예	모델 ID.
messages	array	예	role과 content를 가진 메시지 배열.
stream	boolean	아니오	스트리밍 응답, 기본 false.
temperature	number	아니오	샘플링 온도, 0–2, 기본 1.
max_tokens	integer	아니오	최대 생성 토큰 수.
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, Volcengine Doubao 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

Volcengine Doubao Seedream 및 유사 멀티모달 모델. 전체 경로: https://api.robovai.com/v1/multimodal/images/generations

동영상 생성

비동기 인터페이스: 작업을 제출해 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	string	예	모델 ID(예: Seedance 시리즈).
prompt	string	예	동영상 설명 프롬프트.
duration	number	아니오	동영상 길이(초), 예: 5.
resolution	string	아니오	해상도, 예: 720p, 1080p.
ratio	string	아니오	화면비, 예: 16:9, 9:16.
fps	number	아니오	프레임 속도, 예: 24, 30.

요청 예시

{
  "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(예: tts-1).
input	string	예	합성할 텍스트.
voice	string	예	음성, 예: alloy, echo, nova.
response_format	string	아니오	오디오 형식: mp3/opus/aac/flac, 기본 mp3.
speed	number	아니오	속도, 0.25–4, 기본 1.