API 레퍼런스

공개 REST 경로, 요청, 오류 봉투입니다.

개요

공개 REST는 이미지, 영상, 오디오 생성을 개인 키로 접수하고 작업을 조회·취소합니다. 생성 경로는 모두 /v1로 시작합니다. 서버 주소는 이 문서에 적지 않습니다. 코드에서는 환경변수로 받으세요.
이 문서의 경로, 필드, 한도, 오류는 서버 계약과 공개 라우트를 하나씩 대조해 적었습니다. 여기에 없는 경로는 공개 API가 아닙니다.

인증

Authorization: Bearer <개인 키> 헤더를 보냅니다. 키는 로그인과 키에서 만들고, 쓰는 기능에 맞는 권한을 허용해야 합니다.
경로필요한 기능 권한
/v1/models/image, /v1/images…이미지 생성
/v1/models/video, /v1/videos…, /v1/models/audio, /v1/audio…영상 생성
POST /assets에셋 업로드
  • 인증 헤더는 하나만 보냅니다. Authorization과 X-Api-Key를 함께 보내면 401입니다.
  • 키가 틀렸거나 만료·폐기됐거나 권한이 모자란 경우는 모두 같은 401입니다. 이유를 구분해 알려 주지 않습니다.
  • 계정의 연령 확인이 끝나지 않았으면 403입니다.
  • 모든 /v1 응답에 Cache-Control: no-store가 붙습니다.
  • 키별 지출 한도가 걸려 있으면 잔액이 있어도 한도를 넘는 접수는 거절됩니다. 오류와 지출을 보세요.

경로

/v1 아래 공개 경로는 이 표가 전부입니다. 본문이 있는 요청은 Content-Type: application/json입니다.
메서드경로설명성공
GET/v1/models/image이미지 모델, 옵션 값 목록, 기본값, 가격200
POST/v1/images이미지 접수202
GET/v1/images내 이미지 작업 목록200
GET/v1/images/:id이미지 작업 조회200
POST/v1/images/:id/cancel이미지 작업 취소200
GET/v1/models/video영상 모델과 체리 견적표200
POST/v1/videos영상 접수202 (이미 접수된 키는 200)
GET/v1/videos내 영상 작업 목록200
GET/v1/videos/:id영상 작업 조회200
POST/v1/videos/:id/cancel영상 작업 취소200
GET/v1/models/audio오디오 모델과 곡당 체리200
POST/v1/audio오디오 접수202
GET/v1/audio/:id오디오 작업 조회200
POST/v1/audio/:id/cancel오디오 작업 취소200
POST/assets파일 업로드(멀티파트). 레시피의 업로드한 파일 쓰기201
오디오 목록 경로는 없습니다. 접수 응답의 작업 id를 저장해 두세요.
웹훅을 관리하는 경로(/webhooks/endpoints…)와 사용량 경로(/usage/developer/…)는 로그인한 사람의 화면이 쓰는 경로입니다. 개인 키로는 부를 수 없습니다. 웹훅을 보세요.
모델 조회 경로는 웹 입력창이 읽는 것과 같은 모델 정의를 돌려줍니다. 옵션 값의 목록, 기본값, 가격이 한 응답에 있습니다. 생략한 옵션은 모델 정의의 기본값이 쓰이고, 모델이 지원하지 않는 값은 조용히 바뀌지 않고 400으로 거절됩니다.

접수 요청

세 요청 모두 모르는 필드를 보내면 무시하지 않고 400으로 거절합니다. 본문 크기는 이미지 64KiB, 영상과 오디오 16KiB까지입니다.

이미지

필드필수뜻
modelId예GET /v1/models/image의 모델 id
prompt예1~4,000자
negativePrompt아니요1~4,000자. 지원하는 모델에서만
aspectRatio, resolution, quality, style아니요모델이 지원하는 값. 생략하면 모델 기본값
candidateCount아니요1~12. 기본 1. 모델의 maxCandidates를 넘으면 거절
background아니요auto 또는 transparent. 투명 배경을 지원하는 모델에서만
seed아니요0~2,147,483,647. 시드를 지원하는 모델에서만
referenceAssets아니요{ "assetId", "revision" } 배열. 최대 5개, 모델의 한도 안에서
maxCherry예감수할 체리 상한. 1~10,000,000 정수
idempotencyKey예8~128자
공개 경로에서는 성인 생성을 열지 않습니다.

영상

영상은 캔버스 문서의 한 revision이 요청의 기준입니다. 모델, 길이, 해상도는 문서가 정하고 서버가 서빙 중인 카탈로그로 검증합니다. 문서를 접수하려면 그 문서의 편집 권한이 있어야 합니다. 보기 전용이면 403, 멤버가 아니면 404입니다.
필드필수뜻
documentId예캔버스 문서 id
revision예양의 정수. 문서의 revision
candidateCount아니요1~12. 기본 1. 후보마다 작업이 하나씩 생깁니다
tier아니요draft(더 싼 초안) 또는 final(본 생성). 기본 final
draftJobId아니요본 생성을 이어 갈 초안 작업 id
maxCherry예감수할 체리 상한. 후보 전체의 합계와 비교합니다
idempotencyKey예8~128자
같은 입력으로 끝난 초안이 있는데 draftJobId 없이 final을 보내면 400입니다. 메시지가 초안 작업 id를 알려 줍니다.

오디오

곡 수 외의 옵션은 공급이 공표하지 않아 받지 않습니다.
필드필수뜻
modelId예GET /v1/models/audio의 모델 id
prompt예1~2,000자
count아니요곡 수. 1, 2, 4 중 하나. 생략하면 모델 기본값
maxCherry예감수할 체리 상한. 곡 수만큼의 합계와 비교합니다
idempotencyKey예8~128자
곡마다 작업이 하나씩 생겨 jobs에 담깁니다.

금액 상한과 멱등

  • maxCherry는 이 요청이 감수하는 체리 상한입니다. 서버가 방금 계산한 견적이 이 값을 넘으면 아무것도 만들지 않고 400으로 거절합니다. 이때 details.required_cherry가 견적입니다. 생략하면 거절됩니다. 기본값은 없습니다.
  • idempotencyKey는 8자 이상 128자 이하이고, Idempotency-Key 헤더로도 보낼 수 있습니다. 이미지·영상·오디오 접수와 이미지 취소에서 됩니다. 본문과 헤더를 둘 다 보내면 같은 값이어야 하고, 다르면 400입니다.
  • 같은 키에 같은 본문을 다시 보내면 기존 작업을 돌려줍니다. 같은 키에 다른 본문은 409이고 details.conflict_reason이 idempotency_key_reused입니다.
  • 영상은 이미 끝나 환불된 요청의 키를 다시 쓰면 409입니다. 새 키로 접수하세요.
  • 후보가 여럿인 영상은 첫 후보가 원래 키를 쓰고 다음 후보부터 서버가 키를 파생합니다. 같은 요청을 다시 보내면 같은 작업들이 돌아옵니다.
  • 가격이 확정되지 않은 모델과 옵션 조합은 접수되지 않습니다. 영상은 422 PRICE_UNPUBLISHED와 details.price_reason, 이미지는 400입니다.

작업 응답

접수와 조회가 돌려주는 모양은 종류마다 다릅니다.
호출응답 본문
POST /v1/images작업 객체 그대로(id, status, …)
GET /v1/images/:id{ job, outputs, poll_after_seconds? }
POST /v1/images/:id/cancel{ job }
GET /v1/images{ items, nextCursor }
POST /v1/videos{ jobs }
GET /v1/videos/:id, 취소{ job }
GET /v1/videos{ items, next_cursor }
POST /v1/audio{ jobs }
GET /v1/audio/:id{ job, result? }
POST /v1/audio/:id/cancel{ job }
상태는 아래와 같습니다. 끝난 상태는 이미지 done·failed, 영상과 오디오 succeeded·failed입니다.
종류상태
이미지queued, running, done, failed
영상queued, submitting, submission_uncertain, processing, succeeded, failed
오디오queued, running, succeeded, failed
작업 객체의 주요 필드입니다. 이미지는 카멜케이스, 영상과 오디오는 스네이크케이스입니다.
종류주요 필드
이미지id, status, request, priceSnapshot, chargedAmount, cancelRequested, createdAt, updatedAt. 끝나면 done에 result, failed에 error(code, message, retryable), doneAt
영상id, document, status, failure, result, billing, reserved_cherry, tier, stalled, created_at, updated_at
오디오id, model_id, document_id, node_id, status, failure, billing, created_at, updated_at
  • 이미지 조회는 완료 시 후보마다 읽기 링크(outputs)를 함께 줍니다. 항목은 asset, url, expiresAt, expiresInSeconds(900)입니다.
  • 오디오 조회는 완료 시 result에 읽기 링크를 줍니다. 항목은 asset, kind, url, expiresAt, expiresInSeconds(900)입니다.
  • 영상 작업의 result는 결과 자산 참조이고 url은 조회할 때마다 새로 서명됩니다.
  • 읽기 링크는 15분 동안 쓸 수 있습니다. 만료되면 다시 조회합니다.
  • 삭제된 자산은 링크 없이 빠집니다.
  • failure와 error의 code는 닫힌 목록이고 환불 규칙은 오류와 지출에 있습니다.
  • 영상의 stalled가 true면 실행 제한 시간(접수 후 45분)을 넘겼다는 뜻입니다.

기다리는 시간

진행 중인 작업을 다시 조회하기까지 기다릴 초입니다. 이보다 촘촘히 부르면 읽기 한도만 소모합니다.
종류어디에값
이미지응답 최상위 poll_after_seconds5
오디오job.poll_after_seconds10
영상응답에 없음10초 간격을 권합니다

목록

  • 최신순이고 cursor로 다음 쪽을 읽습니다. 이미지는 nextCursor, 영상은 next_cursor이며 null이면 마지막입니다.
  • limit은 1~100 정수이고 기본 50입니다. 범위 밖이면 400입니다.
  • 이미지 목록은 status(queued, running, done, failed)로 거를 수 있습니다.
  • 이미지 목록 항목은 요약입니다. 프롬프트는 앞 120자만 담깁니다. 전체는 단건 조회로 읽습니다.
  • 내가 소유한 작업만 보입니다. 없는 작업과 남의 작업은 모두 404입니다.

모델 조회 응답

경로응답눈여겨볼 필드
GET /v1/models/image{ models, defaults }모델마다 id, label, options, capabilities(aspectRatios, resolutions, qualities, styles, maxCandidates, maxReferenceAssets, supportsNegativePrompt, supportsSeed), price(billing, cherry, lines)
GET /v1/models/video{ models }모델마다 supported_resolutions, supported_aspect_ratios, supported_durations, cherry_quotes, priceable, price_unpublished_reason
GET /v1/models/audio{ default_model_id, models }모델마다 id, label, options, cherry_per_track(환율을 못 얻으면 null)
이미지는 price.cherry가 null인 모델을 접수할 수 없습니다(400). 영상은 priceable이 false인 모델도 목록에 보이지만 접수하면 422입니다.

취소

종류규칙
이미지본문 { "idempotencyKey": "…" }가 필요합니다(Idempotency-Key 헤더로도 가능). 대기 중이면 바로 취소됩니다. 진행 중이면 취소 요청만 기록되고(cancelRequested) 작업이 멈출 때 정산됩니다. 이미 끝난 작업은 409
영상본문 없음. 대기(queued) 중인 작업만 취소됩니다. 보류한 체리가 환불됩니다
오디오본문 없음. 대기 중인 작업만 취소됩니다. 전액 환불됩니다
이미 시작됐거나 끝난 작업은 409이고 details.cancel_reason이 already_started입니다. 이미 취소된 작업을 다시 취소하면 같은 응답을 돌려줍니다.

요청 한도

개인 키로 부르는 요청은 사용자별 시간당 한도를 셉니다. 조회(GET)는 읽기, 그 밖(접수·취소·업로드)은 쓰기입니다. 두 버킷은 서로를 먹지 않습니다.
기능 권한읽기쓰기
이미지 생성3,000300
영상 생성(영상·오디오 경로 포함)3,000300
에셋 업로드해당 없음120
한도 응답 헤더와 429 구별법은 오류와 지출에 있습니다. 이 시간당 한도는 개인 키로 부르는 요청에만 적용됩니다.
접수에는 이 한도와 별개로 동시에 진행할 수 있는 작업 수와 시간당·하루 접수 수 제한이 있습니다. 값은 기본값이고 서버 설정으로 달라질 수 있습니다. 걸리면 429 RATE_LIMITED이고 details.limit_kind가 image_active, video_active, audio_active, image_daily, video_hourly 중 하나입니다.
limit_kind뜻
image_active진행 중인 이미지 작업이 1개를 넘을 수 없습니다
video_active진행 중인 영상 작업은 24개까지입니다
audio_active진행 중인 오디오 작업은 8개까지입니다
image_daily하루에 접수할 수 있는 이미지 작업은 10개까지입니다(서버 시각 기준 하루). 실패한 작업은 세지 않습니다
video_hourly영상 작업은 시간당 60개까지 접수됩니다

오류

모든 오류는 같은 봉투입니다.
오류 봉투 — json
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "...",
    "requestId": "...",
    "details": {}
  }
}
requestId는 응답 헤더 X-Request-Id와 같습니다. 코드별 상태와 대응은 오류와 지출에 있습니다.

관련