빠른 시작
키 하나, 요청 형식 하나로 모든 이미지·영상 모델을. 작업을 제출하고, 폴링하고, 파일을 받으세요.
/data/models.json에 있습니다.POST /v1/chat/completions에서 같은 크레딧으로 토큰 단위로 결제합니다. chat completions를 참고하세요.| 베이스 URL | https://api.revana.si/v1 |
| 인증 | Authorization: Bearer <key> |
| 제출 | POST /v1/generations |
| 폴링 | GET /v1/generations/{id} |
| 모델 | GET /v1/models (키 불필요): 지금 생성할 수 있는 모든 모델 |
| 잔액 | GET /v1/balance: 키의 계정에서 사용할 수 있는 금액 |
| 업로드 | POST /v1/uploads: 내 컴퓨터의 참조 파일을 위한 링크 |
| 형식 | JSON 입력, JSON 출력. 가격은 USD, 100크레딧 = $1. |
| 기계 판독 가능 | /openapi.json · /llms.txt |
인증
계정에서 키를 만든 다음 모든 요청에 Bearer 토큰으로 보내세요. 키는 서버에만 보관하고 브라우저나 모바일 앱에 넣어 배포하지 마세요.
생성 제출하기
모델 id와 input를 보내세요. 응답은 생성 id와 상태 queued과 함께 즉시 돌아오며, 작업은 백그라운드에서 이루어집니다.
| 필드 | 유형 | 설명 |
|---|---|---|
model | string, 필수 | 모델 페이지의 모델 id, 예: seedance-2.5. |
input | object, 필수 | 프롬프트와 설정입니다. 입력 필드를 참고하세요. 알 수 없는 필드는 거부됩니다. |
max_cost_usd | number, 선택 | 이 생성에 지불할 최대 금액이며, 100(기본값)까지 가능합니다. 이보다 가격이 높은 경로는 건너뛰며, 남은 경로가 없으면 요청은 422 max_cost_exceeded로 응답합니다. |
max_wait_s | integer, 선택 | 이 초 수보다 오래 걸릴 것으로 예상되는 경로는 건너뜁니다. 그 시간이 지나면 새 경로는 시도하지 않지만, 이미 실행 중인 경로는 끝까지(최대 40분) 실행되며 결과를 전달하면 청구됩니다. |
Idempotency-Key | 헤더, 선택 | 최대 200자입니다. 같은 키와 본문을 다시 보내면(타임아웃이나 503 후) 두 번째 생성이 아니라 같은 생성을 돌려받습니다. 같은 키에 다른 본문을 보내면 409 idempotency_conflict입니다. |
결과 받기
모델별 엔드포인트와 완료 웹훅을 원하시나요? 요청 ID, 상태/결과 URL, 지원되는 fal 별칭, 마이그레이션 제한은 fal 호환 큐 API를 참고하세요.
status가 succeeded 또는 failed가 될 때까지 몇 초마다 폴링한 다음, output.urls의 파일을 키로 다운로드하세요. 첫 번째는 GET /v1/generations/{id}/content, 이미지 모델이 여러 개를 반환하면 /content/2, /content/3…입니다. 이미지는 보통 몇 초가 걸리고, 영상은 모델과 길이에 따라 1분 미만에서 몇 분까지 걸립니다.
완료된 생성:
입력 필드
모든 모델에서 같은 이름을 사용합니다. 각 모델이 받는 필드와 값, 기본값은 모델별로 /data/models.json(options, tasks)에 나열되어 있습니다. 모델이 지원하지 않는 필드나 값이 있으면 요금이 청구되기 전에 422 invalid_input 오류로 요청이 거부됩니다.
| 필드 | 유형 | 용도 |
|---|---|---|
prompt | string | 생성할 내용. 텍스트 투 이미지와 텍스트 투 비디오에 필수입니다. |
image_url | string (URL) | 이미지 투 비디오의 시작 프레임, 또는 이미지 투 이미지에서 편집할 이미지. |
end_image_url | string (URL) | 첫 프레임 + 마지막 프레임을 지원하는 모델의 마지막 프레임. |
image_urls | string[] | 참조 이미지, 모델의 한도까지. |
resolution | string | 720p, 1080p, 2K... 모델이 지원하는 해상도 중 하나. |
duration | number | 초 단위 영상 길이, 모델이 지원하는 길이 중 하나. |
aspect_ratio | string | 16:9, 9:16, 1:1... |
audio | boolean | 모델이 지원하는 경우 영상과 함께 소리를 생성합니다. 가격이 달라질 수 있습니다. |
negative_prompt | string | 이를 받는 모델에서 피할 내용. |
video_url | string (URL) | 변환, 연장 또는 업스케일할 클립. 길이가 측정되며 초당 과금 모델에서는 청구됩니다. |
audio_url | string (URL) | 토킹 아바타 또는 립싱크 모델이 이에 맞춰 움직이는 음성 또는 소리. |
quality | string | 등급별로 가격이 매겨지는 모델의 품질 등급(예: low, medium, high). |
seed | integer | 시드를 받는 모델의 시드. |
Seedance 2.5의 기본값은 720p, 5초(4~30), 16:9, 소리 없음이며 다음도 받습니다.
| 필드 | 유형 | 용도 |
|---|---|---|
video_url | string (URL) | 편집할 4~30초 클립. 결과는 원래 길이를 유지하므로 duration는 생략하세요. |
video_urls | string[] | 참조 클립, 최대 10개이며 합계 30초까지. 해당 초는 영상 입력 요율로 청구됩니다. |
audio_urls | string[] | 참조 사운드, 최대 10개이며 합계 30초까지. |
image_url 은(는) 정확한 첫 프레임이므로 참조 미디어와 함께 쓸 수 없습니다. 더 느슨한 시각적 참조에는 image_urls를 사용하세요. end_image_url에는 image_url가 필요합니다. 미디어는 직접 다운로드할 수 있는 공개 https URL이어야 합니다.
Nemesis
nemesis 은(는) 클립을 내 사람, 제품, 장소로 다시 연출합니다. 클립의 움직임, 타이밍, 카메라는 그대로이며 최대 8장의 참조 이미지가 연기합니다. 결과는 클립의 길이와 형태를 유지합니다. 가격은 Seedance 2.5 편집 요율에 초당 $0.02를 더한 값(480p, 720p, 1080p에서 $0.08, $0.17, $0.36)이며, 입력 클립의 초와 출력 영상에 대해 초당 계산됩니다.
Scenario ALTER의 방식을 따릅니다. 클립 자체가 무음으로 편집되며, 변경이 이미 반영된 클립의 한 프레임을 다시 그려 첫 참조로 사용하고, 클립 자체의 소리는 이후에 다시 입힙니다. 사람이 여러 명이면 이미지는 첫 프레임에서 사람들이 서 있는 순서대로 왼쪽에서 오른쪽으로 매칭됩니다.
| 필드 | 유형 | 용도 |
|---|---|---|
video_url | string (URL), 필수 | 다시 연출할 4~30초 클립. |
image_urls | string[], 필수 | 1~8장의 참조 이미지. |
roles | string[] | 이미지마다 하나씩: person(기본값), product, location, look. |
target_frame | boolean | 렌더링 전에 클립의 첫 프레임이 같은 포즈, 크기, 조명으로 변경이 반영되어 다시 그려지고 첫 참조로 전송되므로, 머리카락, 얼굴, 옷이 내 이미지에 충실하게 유지됩니다. nemesis에서는 기본적으로 켜져 있고 nemesis-lite에서는 꺼져 있습니다. 무료입니다. |
guide | string | nemesis-lite 전용입니다(nemesis는 항상 클립 자체를 편집합니다). clip(목표 프레임이 있을 때의 기본값): 클립 자체의 화면을 따릅니다. people(없을 때의 기본값): 사람은 교체되고 배경은 유지됩니다. scene: 보이는 모든 것이 참조와 프롬프트에서 나옵니다. |
sound | string | original (nemesis의 기본값은 켜짐): 클립 자체의 소리를 다시 입힙니다. none(nemesis-lite의 기본값): 무음. |
face_mesh | boolean | nemesis-lite 전용입니다. 클립의 모든 얼굴을 추적해 새 얼굴이 표정, 눈, 입술을 유지하도록 합니다. guide: "people"에서는 기본적으로 켜져 있고 scene와 clip에서는 꺼져 있습니다. 끄려면 false를 보내세요. 결과에는 표시되지 않습니다. |
resolution | string | 480p, 720p(기본값) 또는 1080p. |
prompt | string | 선택적 지시 사항, 최대 5000자. |
nemesis-lite에서 아무도 없는 클립을 guide: "people"와 함께 보내면 invalid_input 오류로 거부되며 요금이 청구되지 않습니다. scene 또는 clip와 함께 보내세요.
소요 시간. 먼저 클립이 준비됩니다. nemesis에서는 목표 프레임을 그리며 약 15~40초, nemesis-lite에서는 음성을 분리하고 각 프레임이 깊이 가이드가 되며 8초 클립은 약 25초, 30초 클립은 1분 30초가 걸립니다. 그다음 영상이 렌더링되며 대부분의 대기 시간이 여기에 쓰입니다. 480p 8초 클립은 약 4~7분이 걸립니다. 생성이 끝날 때까지 폴링하세요.
Nemesis Lite
nemesis-lite 은(는) nemesis와 같은 입력을 받아 Wan 3.0에서 렌더링합니다. 더 저렴하며 얼굴과 세부 묘사의 충실도는 약간 떨어집니다. 클립은 2~15초입니다. 가격은 Wan 3.0 요율에 초당 $0.02를 더한 값(480p, 720p, 1080p에서 $0.07, $0.11, $0.19)이며, 입력 클립의 초와 출력 영상에 대해 초당 계산됩니다.
생성 객체
| 필드 | 유형 | 설명 |
|---|---|---|
id | string | 폴링에 사용하는 생성 id(gen_…). |
object | string | 항상 generation. |
model | string | 요청한 모델. |
status | string | 상태를 참고하세요. |
message | string | 제공업체와 결과를 확인하는 동안에만: 진행 중인 상황. |
quoted_usd | number | 가장 저렴한 경로, 즉 가장 먼저 시도되는 경로의 가격입니다. 그 경로가 만들지 못하고 더 비싼 대체 경로가 만들면 그 경로의 가격이 청구되며, reserved_usd까지입니다. |
reserved_usd | number | 잔액에서 보류되는 금액: 다른 경로를 시도한 뒤 더 비싼 대체 경로가 만든다고 가정할 때 이 생성에 들 수 있는 최대 금액입니다. 차액은 정산될 때 해제됩니다. quoted_usd를 넘게 지불하지 않으려면 max_cost_usd를 그 값으로 설정하세요. 그러면 더 비싼 대체 경로는 건너뜁니다. |
output | object | null | 성공 시: 결과 파일인 urls(이미지 모델은 여러 개를 반환할 수 있음)에 width와 height가 있고, 영상에는 duration_s와 has_audio도 있습니다. 파일은 만료되므로 바로 다운로드하세요. |
cost_usd | number | null | 청구된 금액. 생성이 성공하면 설정되고, 실패하면 0입니다. |
attempts | number | 대체 경로를 포함해 시도된 경로. 성공한 경로만 청구됩니다. |
error | object | null | 실패 시: code, message, retryable이며, 콘텐츠 거부에는 reason도 있습니다. 생성이 실패한 이유를 참고하세요. |
created_at, completed_at | string | ISO 8601 타임스탬프. |
상태
| 상태 | 의미 |
|---|---|
queued | 접수됨, 경로를 기다리는 중. |
running | 생성 중. 경로가 실패하면 다음 경로로 넘어가는 동안, 그리고 결과를 확인하는 동안(message 참고) 작업은 running 상태로 유지됩니다. |
succeeded | 완료. output.urls에 파일이, cost_usd에 지불한 금액이 있습니다. |
failed | 모든 경로가 실패했거나 입력이 거부되었습니다. 요금은 청구되지 않습니다. |
결제
- 선불 크레딧으로 지불하며, 1달러에 100크레딧이고 $10~$5,000 팩으로 구매합니다. 모든 가격은 정수 크레딧입니다.
- 제출할 때
reserved_usd가 잔액에서 보류됩니다. 생성이 실패하면 전액 해제됩니다. - 생성이 성공했을 때만, 그것을 만든 경로의 견적 가격으로 청구됩니다. 보통은
quoted_usd의 첫 번째 경로입니다. 대체 경로가 만들어야 하면 비용이 더 들 수 있습니다. 그 경로의 가격이거나, 그 전에 시도한 경로가 공급업체에 의해 청구되었다면 그 시도들의 비용에 10%를 더한 금액 중 더 큰 쪽입니다.reserved_usd를 넘지는 않습니다. - 월 할당량이나 분당 제한은 없습니다. 잔액과
max_cost_usd가 한도입니다. - 각 모델의 가격은 해당 모델 페이지와 가격표에 있습니다.
잔액
키가 속한 계정입니다. 대량 배치 전에 확인하세요. 비용이 없으며 생성 한도에 포함되지 않습니다.
| 필드 | 의미 |
|---|---|
available_usd | 새 생성이 예약할 수 있는 금액. reserved_usd가 이보다 큰 제출은 402 insufficient_credits를 받습니다. |
held_usd | 아직 실행 중인 생성에 예약된 금액. 사용하지 않은 부분은 정산될 때 돌아옵니다. |
balance_usd | 사용 가능 금액에 보류 금액을 더한 값. |
spent_usd | 완료된 생성에 청구된 금액, 전체 기간. |
*_credits | 같은 금액을 크레딧(1달러에 100)으로 표시하며, 사용 가능 금액이 실제보다 높게 표시되지 않도록 반올림합니다. |
참조 파일 업로드
참조는 공개 https:// 링크로 전달됩니다. 내 컴퓨터에 있는 파일은 업로드 링크를 요청하고, 그곳으로 바이트를 보낸 다음 돌아온 링크를 사용하세요. 무료입니다.
| 필드 | 의미 |
|---|---|
upload_url | 한 시간 이내에 upload_headers의 헤더(유형과 크기)를 정확히 그대로 사용해 PUT로 파일을 이곳에 보내세요. 그 외에는 거부됩니다. |
url | api.revana.si에 있는 파일의 링크로, expires_at(14일)까지 유효합니다. 키가 필요 없고 파일로 리디렉션되므로 링크를 가져올 수 있는 모든 것이 읽을 수 있습니다. POST /v1/generations에서 참조로 사용하세요. 파일은 곧 삭제됩니다. |
id | upl_… |
이미지(image/*)는 최대 30 MB, 클립(video/*)은 최대 50 MB, 소리(audio/*)는 최대 15 MB입니다. 더 크거나 다른 파일은 413 too_large 또는 400 invalid_request를 받습니다.
생성이 실패한 이유
failed 생성에는 error.code, 요청한 사람에게 보여 주기 위해 작성된 message, 그리고 retryable가 있습니다. 나중에 같은 요청을 다시 보내면 성공할 수 있을 때는 true, 요청 자체를 바꿔야 할 때는 false입니다. 실패한 생성은 절대 청구되지 않습니다.
| 코드 | 재시도 가능 | 발생 시점 |
|---|---|---|
content_policy | no | 모델이 프롬프트나 미디어를 거부했거나 생성한 결과물을 제공하지 않았습니다. reason가 어떤 규칙인지 알려 줍니다. sexual(NSFW 또는 성인 콘텐츠), minors(아동 또는 청소년), copyright(저작권이 있거나 제3자의 자료, 브랜드, 캐릭터), real_person(실존 인물 또는 유명인의 초상), 또는 모델이 이유를 제공하지 않을 때는 other입니다. |
invalid_input | no | 참조를 읽을 수 없었거나, 이미지를 하나만 보냈는데 프롬프트가 @Image2를 언급했거나, 모델이 거부하는 값입니다. 메시지에 어느 쪽인지 표시됩니다. |
model_declined | no | 모델이 이미지나 영상을 만드는 대신 말로 답했습니다. 보통 프롬프트가 필요하지만 보내지 않은 것을 요구하기 때문입니다. 프롬프트가 결과물 자체를 설명하도록 하세요. |
reference_changed | no | 참조 파일이 검사된 후 변경되었습니다. 다시 보내세요. |
max_cost_exceeded | no | 실행할 수 있는 유일한 경로의 비용이 max_cost_usd보다 높습니다. |
model_busy | yes | 모델의 모든 경로가 용량 한계였습니다. 1분 후에 다시 시도하세요. |
model_unavailable | yes | 지금은 어떤 경로도 작업을 받을 수 없습니다. |
timeout | yes | 시간 내에 결과를 반환한 경로가 없거나 max_wait_s가 지났습니다. |
all_routes_failed | yes | 모든 경로가 제공업체 쪽 사유로 실패했습니다. |
오류
오류는 HTTP 상태 코드와 JSON 본문을 사용합니다: {"error": {"code": "...", "message": "..."}}.
| HTTP | 코드 | 발생 시점 |
|---|---|---|
| 400 | invalid_request | 본문이 JSON이 아니거나, model 또는 input가 없거나, API가 모르는 필드가 있습니다. |
| 401 | unauthorized | API 키가 없거나 올바르지 않습니다. |
| 402 | insufficient_credits | 사용 가능 잔액이 reserved_usd를 감당하지 못합니다. 충전한 후 다시 시도하세요. |
| 403 | account_disabled | 계정이 일시 중지되었습니다. 지원팀에 문의하세요. |
| 403 | generation_not_enabled | 키가 가격 조회는 되지만 아직 생성은 할 수 없습니다. |
| 404 | not_found | 계정에 이 id의 생성이 없습니다. |
| 409 | idempotency_conflict | 이 Idempotency-Key는 이미 다른 본문으로 사용되었습니다. |
| 409 | not_ready | 생성이 성공하기 전에 파일을 요청했습니다. |
| 413 | body_too_large | 본문이 1 MB를 초과합니다. 미디어는 URL로 보내세요. |
| 422 | invalid_input | 모델이 지원하지 않는 필드, 값, 조합이거나 읽을 수 없는 미디어입니다. 요금은 청구되지 않습니다. |
| 422 | max_cost_exceeded | 모든 경로의 비용이 max_cost_usd보다 높습니다. |
| 422 | model_not_available | API에 이 id의 모델이 없습니다. id는 모델 페이지에 있습니다. |
| 429 | rate_limited | 한 계정에서 같은 초에 요청이 너무 많습니다(폭주하는 루프를 막기 위한 장치이며 할당량이 아닙니다). Retry-After초 기다리세요. |
| 429 | concurrency_limit | 계정에 진행 중인 생성이 이미 최대 개수입니다. 하나가 끝나면 다시 시도하세요. |
| 503 | busy | 일시적인 부하입니다. 같은 Idempotency-Key로 Retry-After 후에 다시 시도하세요. |
| 503 | model_unavailable | 지금은 이 모델의 경로가 하나도 작동하지 않습니다. 잠시 후 다시 시도하세요. |
| 500 | server_error | 저희 쪽에서 문제가 발생했습니다. 같은 Idempotency-Key로 안전하게 재시도할 수 있습니다. |
모델 목록
모든 모델, 옵션, 가격은 JSON으로 /data/models.json에 게시되며, 이 사이트가 렌더링하는 것과 같은 파일입니다.