01
길이와 해상도는 기본값이 아니라 가격 다이얼입니다
대부분의 영상 엔드포인트는 선택한 해상도의 출력 초 단위로 과금합니다. duration_seconds를 5에서 10으로 올리면 요금은 대략 두 배, 해상도를 한 단계 올리면 또 한 번 그렇습니다. 둘 다 스키마에 가격 영향으로 표시되므로, 견적은 청구서가 아니라 컨트롤 옆에 있어야 합니다.
영상 API 솔루션
해결 과제
영상만 다른 점
영상 요청은 느린 이미지 요청이 아닙니다. 길이, 해상도, 오디오 스위치가 지불 금액과 대기 시간을 정하고, 그것도 첫 프레임이 그려지기 전에 정해집니다.
02
생성 오디오는 별도의 요율입니다
generate_audio가 있는 엔드포인트에서 이 불리언은 요청을 다른 요율로 옮깁니다. 폼이 이를 감추면 매 요청마다 조용히 비싼 쪽을 보내게 됩니다.
03
HTTP 응답은 영상이 아닙니다
createTask는 queued 상태의 taskId와 함께 202 Accepted를 돌려줍니다. 생성은 서버에서 수 분 더 이어집니다. 원래 소켓에서 기다리는 코드는 타임아웃되고, 그동안 작업과 과금은 계속됩니다.
구현 방식
값을 먼저 확정하고, 제출은 한 번만
POST /api/v1/jobs/quote로 실제 본문을 견적내고 그 금액을 보여준 뒤, 같은 본문을 quoteId·expectedCost·저장해 둔 Idempotency-Key와 함께 createTask로 보냅니다. 두 호출 사이에 가격이 바뀌면 업무 코드 40901로 막히고, 나중에 청구서에서 놀랄 일은 없습니다.
생성 호출 하나가 모델, 검증된 입력, 선택적 콜백을 실어 보냅니다. HTTP 202는 접수이지 완료가 아닙니다.
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}계약
먼저 못 박아 둘 항목
| 필드 또는 헤더 | 값 또는 상한 |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
좌우로 밀어 모든 항목을 확인하세요.
연동
첫 호출에서 운영까지
- 01모델 페이지에서 엔드포인트를 고르고 model 값을 그대로 복사합니다. 끝에 붙은 작업 유형도 값의 일부입니다.
- 02보낼 본문을 견적내고 estimatedCost·quantity·unit을 제출 버튼 옆에 표시합니다.
- 03백엔드에서 Idempotency-Key와 함께 보내고, data.taskId를 자체 레코드에 저장한 뒤 클라이언트에 바로 응답합니다.
- 04서명된 콜백으로 마무리하고, 보조로 지수 백오프를 쓴 recordInfo를 두며, URL이 만료되기 전에 파일을 내려받습니다.
적합성
이 경로가 맞는 경우
이럴 때 고르세요
- 광고·예고편·루프·소셜 컷처럼 완성된 영상 파일이 필요하고, 한 편당 몇 분의 지연을 감수할 수 있다.
- 길이·해상도·오디오를 사용자가 고르게 해야 하고, 모든 조합이 확정 전에 가격으로 제시되어야 한다.
이럴 때는 다른 길로
- 한 번의 요청 안에서 답이 필요한 경우. 텍스트 모델은 스트리밍하지만 영상은 그렇지 않습니다.
- 생성 도중에 취소할 생각이라면. 접수된 작업은 종단 상태까지 달리고, 돌아오는 것은 쓰지 않은 보류액뿐입니다.
근거
직접 확인할 수 있는 것
모든 필드는 공개 스키마에서 옵니다
모델 페이지의 폼은 해당 엔드포인트의 input_schema로 생성되고, 서버도 같은 문서로 검증합니다. 선언되지 않은 필드는 조용히 버려지지 않고 400이 됩니다.
견적은 추정이 아니라 상한입니다
createTask는 견적액을 보류하고 cost와 settled: false로 돌려줍니다. 최종 청구는 보류액을 넘지 않으며, 실패나 만료 시에는 전액 해제됩니다.
키마다 쓸 수 있는 상한을 따로 겁니다
일별·월별·누적 상한을 정하고, 쓸 수 있는 모델과 접속 IP까지 지정할 수 있습니다. 쓰기 요청은 모두 같은 멱등 키를 받습니다.
출시 전
확인해 둘 플랫폼 동작
- 그 엔드포인트를 오늘 호출할 수 있는지 확인하세요. 이용 가능 여부는 패밀리가 아니라 엔드포인트 단위로 공개됩니다.
- taskId와 Idempotency-Key를 브라우저 세션 밖에 함께 저장하세요.
- 본문을 읽기 전에 콜백 서명을 검증하고, 전달은 반복된다고 전제하세요.
- 완성된 미디어는 자체 스토리지로 복사하세요. 생성 결과 보관 기간은 14일입니다.
자주 묻는 질문
이 페이지에서 자주 나오는 질문
엔드포인트, 요청한 길이, 그때의 대기열에 달려 있고 그래서 이 API는 비동기입니다. 202를 요청의 끝으로, 콜백이나 상한을 둔 폴링을 작업의 끝으로 보세요. 동기식 영상 엔드포인트는 없습니다.
없습니다. createTask가 202를 돌려준 순간부터 작업은 종단 상태까지 진행됩니다. 실패하거나 만료되면 보류는 전액 해제되고, 성공해도 보류액을 넘겨 청구되지 않습니다.
해당 엔드포인트 스키마에서 가격에 영향한다고 표시된 필드, 보통 duration_seconds·resolution·generate_audio입니다. 확정 전에 그 조합의 금액을 보려면 실제 본문을 견적내세요.
오디오 필드를 선언한 엔드포인트에서, 직접 켠 경우에만 포함됩니다. generate_audio는 요율을 바꾸기 때문에 화질 토글이 아니라 가격에 영향하는 컨트롤로 표시됩니다.
모델
이 작업에 바로 호출할 수 있는 모델
각 링크는 해당 모델 계열 페이지로 이동합니다. 입력, 상한, 콘텐츠 방침, 단위당 현재 가격을 그곳에서 확인할 수 있습니다.
다음
영상 엔드포인트를 비교하고 한 번 돌려보기
길이·해상도·오디오·가격으로 영상 엔드포인트를 비교한 뒤, 같은 요청을 서버에서 보내고 작업 ID로 추적하세요.