01
필드 이름과 기본값은 거의 맞지 않습니다
추측하지 말고 엔드포인트마다 매핑을 적으세요. 입력은 additionalProperties가 닫힌 공개 스키마로 검증되므로, 빠뜨린 필드는 로그의 경고가 아니라 첫 운영 요청에서의 400입니다.
이전 가이드
해결 과제
같은 작업, 다른 계약
깔끔하게 옮겨지는 것은 모델 부분뿐입니다. 옮겨지지 않는 것은 그 주변 전부입니다. 어떤 필드가 필수인지, 기본값은 무엇인지, 참조 이미지는 어떻게 들어가는지, 돈은 언제 묶이는지, 그리고 처음 보는 상태를 만났을 때 코드가 무엇을 해야 하는지.
02
돈은 완료가 아니라 접수 시점에 묶입니다
createTask는 견적액을 보류하고 cost와 settled: false로 돌려줍니다. 지금 쓰는 공급자가 성공 시에만 청구한다면, 트래픽을 옮기기 전에 정산 작업이 보류 개념을 이해해야 합니다.
03
오류 어휘는 닫혀 있고 작습니다
아홉 개의 값이 모든 실패를 덮고 content_rejected도 그중 하나입니다. 거부는 예외가 아니라 종단 작업입니다. 전환 후가 아니라 전환 전에 기존 오류 분기를 이 아홉 개로 매핑하세요.
구현 방식
엔드포인트 하나를 섀도로 돌리고, 숫자를 비교한 뒤 옮기세요
워크플로 하나를 골라 현재의 입력·출력·실패·단가를 기록하고 같은 조건으로 여기서도 돌리세요. jobs/quote의 견적을 오늘 지불액과 비교하고, 두 경로를 플래그 뒤에 함께 살려 둔 채 숫자가 버티는 동안만 비중을 올리세요.
먼저 견적을 내세요. 생성과 똑같은 검증과 접수 판정을 거치지만 자금은 묶지 않고 작업도 시작하지 않습니다.
POST /api/v1/jobs/quote
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p"
}
}200 OK — nothing reserved, nothing started
{
"code": 200,
"msg": "success",
"request_id": "req_example_quote",
"data": {
"quoteId": "qte_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "<publisher>/<model>/text-to-video",
"estimatedCost": "0.750000",
"maxCharge": "0.750000",
"currency": "USD",
"quantity": "5",
"unit": "second",
"expiresAt": "2026-09-12T12:05:00Z"
}
}계약
먼저 못 박아 둘 항목
| 필드 또는 헤더 | 값 또는 상한 |
|---|---|
| POST /api/v1/jobs/quote | no hold · signed quote valid 5 min |
| quoteId + expectedCost | 40901 when the price moved |
| 402 | 40201 balance · 40202 spend cap |
| published call name | immutable · renames keep a 308 |
좌우로 밀어 모든 항목을 확인하세요.
연동
첫 호출에서 운영까지
- 01엔드포인트 하나를 골라 대표 요청 열 건과 그 결과물, 현재 비용을 수집합니다.
- 02모든 필드를 대상 엔드포인트의 input_schema로 매핑하고 그 표를 버전과 함께 보관합니다.
- 03매핑한 본문마다 견적을 내고 estimatedCost·quantity·unit을 오늘의 청구와 비교합니다.
- 04섀도, 카나리, 비중 상향 순으로 진행하되 모든 단계에서 기존 경로를 호출할 수 있게 둡니다.
적합성
이 경로가 맞는 경우
이럴 때 고르세요
- 이미지·영상·텍스트에 걸쳐 하나의 잔액, 하나의 소비 상한, 하나의 작업 계약을 쓰고 싶다.
- 병목이 모델 품질이 아니라 콘텐츠 정책이나 모델별 이용 가능 여부다.
이럴 때는 다른 길로
- 전부를 당일에 전환해야 하는 경우. 계약 차이는 엔드포인트마다, 그것도 늦게 드러납니다.
- 클라이언트에서 모델을 직접 호출하는 경우. 여기서 키는 서버의 것입니다.
근거
직접 확인할 수 있는 것
견적은 진짜 드라이런입니다
POST /api/v1/jobs/quote는 생성과 같은 검증과 접수 판정을 수행하고 estimatedCost·maxCharge·quantity·unit을 돌려주며 아무것도 묶지 않습니다. 서명된 견적은 5분간 유효합니다.
가격이 바뀌면 놀래키는 대신 실패합니다
생성 시 quoteId와 expectedCost를 함께 보내세요. 그사이 가격이 바뀌었다면 접수는 자금을 묶기 전에 업무 코드 40901을 돌려줍니다.
공개된 호출 이름은 움직이지 않습니다
공개된 호출 이름은 계속 유효하고, 이름이 바뀌면 308과 별칭이 남습니다. 매핑 표가 릴리스 사이에 조용히 썩지 않습니다.
출시 전
확인해 둘 플랫폼 동작
- 필드 매핑 표를 버전 관리하고, 엔드포인트마다 성공과 실패 픽스처를 하나씩 남기세요.
- 한 건이라도 보내기 전에 모든 대상 엔드포인트가 호출 가능하고 가격이 붙어 있는지 확인하세요.
- 롤백은 스테이징이 아니라 트래픽을 실은 상태에서 예행연습하세요.
- 마지막 비중을 넘기기 전에 한 청구 주기 내내 보류와 정산을 대조하세요.
자주 묻는 질문
이 페이지에서 자주 나오는 질문
미디어는 안 됩니다. 작업 계약, 필드 이름, 상태 기계, 과금 의미를 모두 매핑해야 합니다. 텍스트가 가장 가까워서, OpenAI 호환 면은 보통 Base URL과 model 값만 바꾸면 됩니다.
보낼 본문 그대로 견적을 내세요. 응답에 estimatedCost·maxCharge·quantity와 단위가 적혀 있어, 작업을 만들지도 자금을 묶지도 않고 같은 잣대로 비교할 수 있습니다.
이용 가능 여부는 엔드포인트 단위로 공개됩니다. 이전 전에 확인하고, 대상이 실제 트래픽을 감당할 때까지 기존 경로를 플래그 뒤에 두세요.
아닙니다. 가격은 명시된 단위당 미국 달러이고 보류와 청구도 달러입니다. 잔액은 환산율이 보이지 않는 토큰이 아니라 돈 그 자체입니다.
모델
이 작업에 바로 호출할 수 있는 모델
각 링크는 해당 모델 계열 페이지로 이동합니다. 입력, 상한, 콘텐츠 방침, 단위당 현재 가격을 그곳에서 확인할 수 있습니다.
다음
워크플로 하나를 매핑하고 견적내기
한 번에 하나의 워크플로만 옮기세요. 필드를 매핑하고, 상태와 오류를 정리하고, 청구를 비교하고, 실제로 시험한 롤백 경로와 함께 전환합니다.
참고 자료: fal model APIs ↗