01
시드는 비교에 도움이 되지만 동일한 픽셀을 보장하지 않습니다
시드를 지원하면 프롬프트, 모델 버전, 크기, 참조 이미지와 함께 저장하세요. 같은 시드여도 일부 endpoint의 결과는 달라질 수 있습니다.
이미지 API 솔루션
해결 과제
범용 폼은 정작 중요한 컨트롤을 잃어버립니다
프롬프트를 넣으면 이미지가 나온다는 말은 십 초쯤 유효합니다. 그다음에는 같은 캐릭터의 두 번째 장, 정사각형이 아닌 3:2, 한 번에 네 장의 후보, 그리고 적어 둘 수 있는 seed가 필요해집니다.
02
크기는 프리셋이 아니라 필드입니다
resolution이나 aspect_ratio를 받는 엔드포인트가 있고, 픽셀 단위 width와 height를 받는 엔드포인트가 있습니다. 잘못 보내면 400이며, 메가픽셀 과금 엔드포인트에서는 고른 크기가 곧 지불 금액입니다.
03
한 번의 호출이 여러 장을 돌려줄 수 있습니다
num_outputs가 있는 엔드포인트에서 과금은 요청 수가 아니라 장수를 따릅니다. 기본값 4는 기본값 1의 네 배이고, 제출 전에 그 차이가 보이는 곳은 견적뿐입니다.
구현 방식
스키마를 읽고, 필드를 남기고, seed를 기록하세요
endpoint 스키마에 따라 입력을 만들고 정확한 요청, 참조 순서, 모델 버전을 결과와 함께 저장하세요. 이후 변형을 비교할 수 있습니다. 재생성은 보장되지 않으므로 원본 결과도 보관하세요.
이미지 작업은 영상과 같은 생성·추적 계약을 씁니다. 차이는 전부 input 안에 있습니다.
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-image",
"input": {
"prompt": "A ceramic teapot on linen, soft window light, muted palette",
"aspect_ratio": "3:2",
"num_outputs": 2,
"seed": 1337
}
}GET /api/v1/jobs/recordInfo?taskId=…
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "succeeded",
"output": {
"assets": [
{
"mime": "image/png",
"url": "https://…/result.png?X-Amz-Signature=…",
"expiresAt": "2026-09-12T12:20:08Z"
}
]
},
"cost": "0.040000",
"settled": true
}
}계약
먼저 못 박아 둘 항목
| 필드 또는 헤더 | 값 또는 상한 |
|---|---|
| input | additionalProperties: false |
| seed · num_outputs · aspect_ratio | declared per endpoint |
| cost + settled: false | hold · final charge never exceeds it |
| errorCode | 9 stable values, content_rejected included |
좌우로 밀어 모든 항목을 확인하세요.
연동
첫 호출에서 운영까지
- 01엔드포인트의 모델 페이지를 열고 seed·negative_prompt·num_outputs와 어떤 크기 필드가 선언되어 있는지 확인합니다.
- 02본문은 input_schema로 구성합니다. additionalProperties가 닫혀 있어 선언되지 않은 키는 무시가 아니라 400입니다.
- 03견적을 내고 Idempotency-Key와 함께 보낸 뒤, taskId·seed·확정된 model 값을 결과 옆에 저장합니다.
- 04콜백이나 recordInfo에서 output.assets를 받아 자체 버킷으로 복사합니다.
적합성
이 경로가 맞는 경우
이럴 때 고르세요
- 텍스트에서 생성하며 여러 제작사를 하나의 요청 형태, 하나의 잔액, 하나의 청구로 다루고 싶다.
- 저장된 요청과 모델 버전으로 조건을 통제한 변형을 비교하려는 경우.
이럴 때는 다른 길로
- 사용자가 이미 가진 사진에서 시작하는 경우. 편집은 자체 참조 계약을 가진 별도 작업입니다.
- 모든 모델에 하나의 고정된 하우스 스타일을 입히고 싶은 경우. 스타일은 이 레이어가 아니라 모델 안에 있습니다.
근거
직접 확인할 수 있는 것
시험용 요청이 곧 운영 요청입니다
모델 페이지에서 조립한 본문이 서버에서 보내는 본문 그대로입니다. 같은 필드, 같은 검증, 같은 견적. 나중에 어긋나는 간이 미리보기는 없습니다.
선언되지 않은 필드는 분명하게 실패합니다
입력은 additionalProperties가 닫힌 엔드포인트 스키마로 검증됩니다. 모델이 선언하지 않은 매개변수는 조용히 무시되지 않고 안정된 errorCode와 함께 400이 됩니다.
결과물은 플랫폼 스토리지에서 제공됩니다
결과는 key·MIME 타입·서명된 url·expiresAt을 가진 output.assets로 돌아옵니다. 모델이 실행된 곳으로 직접 연결되는 링크는 없습니다.
출시 전
확인해 둘 플랫폼 동작
- seed를 어디에 저장할지 출시 전에 정하세요. 남기지 않은 seed는 쓸모가 없습니다.
- 새 키에 반드시 필요한 일일 상한을 설정하고, 필요하면 월간·누적 상한도 더하세요.
- content_rejected를 포함한 닫힌 errorCode 집합을 평범한 제품 상태로 처리하세요.
- 14일 보관 기간 안에 결과물을 자체 스토리지로 미러링하세요.
자주 묻는 질문
이 페이지에서 자주 나오는 질문
원래 입력과 버전, 지원하는 경우 시드를 재사용하세요. 비교 조건은 좁힐 수 있지만 동일한 픽셀을 보장하지 않습니다. 정확히 같은 이미지가 필요하면 원본 출력을 다운로드해 보관하세요.
num_outputs를 선언한 엔드포인트라면 가능하고, 과금은 장수에 비례합니다. 보낼 장수의 금액은 본문을 견적내면 확인됩니다.
엔드포인트가 선언한 것만 씁니다. resolution, aspect_ratio, 또는 width와 height. 모델 페이지에 선택지가 나열되어 있고 범위를 벗어난 값은 작업 생성 전에 거부됩니다.
플랫폼은 따로 두지 않습니다. 동작은 선택한 모델에서 나오며, 모델이 거부하면 errorCode content_rejected를 가진 평범한 종단 작업으로 돌아옵니다.
모델
이 작업에 바로 호출할 수 있는 모델
각 링크는 해당 모델 계열 페이지로 이동합니다. 입력, 상한, 콘텐츠 방침, 단위당 현재 가격을 그곳에서 확인할 수 있습니다.
다음
이미지 엔드포인트를 나란히 비교하기
입력, 크기와 seed 컨트롤, 출력 장수, 장당 가격으로 이미지 엔드포인트를 비교하고, 시험한 요청을 그대로 재사용하세요.