01
경로는 셋이고 실패 방식도 제각각입니다
선언된 이미지 필드는 공개 HTTPS URL, 커밋된 spicy:// 파일 URI, 인라인 data URI를 받습니다. 인라인은 장당 디코딩 후 1 MiB와 8,388,608 픽셀, 본문 전체 2 MiB가 상한입니다. 그보다 크면 업로드 티켓을 써야 합니다.
편집 API 솔루션
해결 과제
어려운 쪽은 참조 이미지를 들여보내는 일입니다
프롬프트는 쉬운 쪽입니다. 다른 쪽은 사용자 휴대폰에 있는 파일이고, 비공개 버킷을 노출하지 않은 채 모델에 닿아야 하며, 작업이 생기기도 전에 검사되는 상한을 만족해야 합니다.
02
파일에 접근할 수 있는 서명된 HTTPS URL은 사용 가능합니다
서명 링크로 쿠키나 별도 로그인 없이 파일을 내려받을 수 있으면 비공개 버킷도 참조할 수 있습니다. 처리 중에는 링크가 유효해야 합니다. 사설 IP, 루프백, user:password URL 인증은 거부됩니다.
03
편집은 생성과 다른 작업입니다
공개 호출 이름은 /edit로 끝나고, 스키마는 보통 image_url이나 image_urls를 요구하며, 일부는 mask_url이나 strength를 더합니다. text-to-image의 model 값을 편집 흐름에 넣으면 완만한 저하가 아니라 검증 실패가 납니다.
구현 방식
한 번 업로드하고, 커밋하고, 파일 URI를 참조하세요
사용자 파일은 업로드 티켓을 받아 선언한 바이트 수 그대로를, 돌려받은 헤더를 모두 붙여 PUT하고, 커밋한 뒤 돌아온 spicy:// URI를 모델의 이미지 필드에 넘깁니다. 그러면 그 참조는 계정 소유가 되고 한 번만 검사되며, 다시 올리지 않고 여러 작업에서 쓸 수 있습니다.
티켓, PUT, 커밋, 생성. 이미 공개된 미디어는 앞의 세 단계를 건너뜁니다.
Ticket → PUT → commit → create
POST /api/v1/common/upload-url
{ "contentType": "image/png", "bytes": 482113 }
→ { "fileId": "fil_01k3…", "uploadUrl": "https://…", "method": "PUT", "headers": { … } }
PUT <uploadUrl> # exactly 482113 bytes, every returned header replayed
POST /api/v1/files/fil_01k3…/commit
→ { "status": "ready", "uri": "spicy://f/fil_01k3…", "sha256": "…" }POST /api/v1/jobs/createTask
{
"model": "<publisher>/<model>/edit",
"input": {
"prompt": "Replace the background with an overcast beach at dusk",
"image_urls": ["spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3"]
}
}계약
먼저 못 박아 둘 항목
| 필드 또는 헤더 | 값 또는 상한 |
|---|---|
| POST /api/v1/common/upload-url | JPEG · PNG · WebP · GIF ≤ 10 MiB |
| POST /api/v1/files/{fileId}/commit | returns spicy://f/fil_… |
| inline data URI | ≤ 1 MiB decoded · ≤ 8192 px per side |
| request body | ≤ 2 MiB · ≤ 16 images |
좌우로 밀어 모든 항목을 확인하세요.
연동
첫 호출에서 운영까지
- 01POST /api/v1/common/upload-url에 contentType과 정확한 바이트 수를 보냅니다. JPEG·PNG·WebP·GIF는 10 MiB까지입니다.
- 02티켓이 돌려준 헤더를 모두 붙여 서명된 URL로 PUT한 뒤 POST /api/v1/files/{fileId}/commit을 호출합니다.
- 03그 엔드포인트의 편집용 model 값으로 createTask를 보내고 spicy:// URI를 image_url이나 image_urls에 넣습니다.
- 04콜백이나 recordInfo에서 output.assets를 읽고 편집된 파일을 직접 저장합니다.
적합성
이 경로가 맞는 경우
이럴 때 고르세요
- 사용자 사진에서 시작하는 제품. 리터칭, 배경 교체, 스타일 변경, 객체 제거 등.
- 같은 참조를 여러 작업에 재사용하면서 매번 다시 올리고 싶지 않은 경우.
이럴 때는 다른 길로
- 원본 이미지가 없는 경우. text-to-image가 더 싸고 계약도 단순합니다.
- 프레임 단위의 영상 편집이 필요한 경우. 편집 엔드포인트가 돌려주는 것은 정지 이미지입니다.
근거
직접 확인할 수 있는 것
업로드는 계정에 묶이고 커밋 시점에 검사됩니다
커밋은 저장된 바이트 수와 미디어 타입을 티켓과 대조하고, 이미지 시그니처를 확인하고, SHA-256을 계산합니다. 그 뒤에야 파일을 참조할 수 있습니다.
인라인 이미지는 레코드로 되돌아오지 않습니다
data URI는 계정에 묶인 파일로 저장됩니다. recordInfo가 돌려주는 정규화된 입력에는 원본 Base64 바이트가 아니라 파일 URI가 들어갑니다.
소재와 결과물은 시계가 다릅니다
올린 소재는 1일, 생성 결과는 14일 보관됩니다. 두 기간 모두 공개 값이며 계정별로 협의하지 않습니다.
출시 전
확인해 둘 플랫폼 동작
- 원본 이미지의 권리를 누가 확인할지 정하세요. 플랫폼이 대신 검사하지 않습니다.
- 티켓을 요청하기 전에 클라이언트에서 미디어 타입과 크기를 검증하세요. 413은 처리하는 것보다 피하는 편이 쌉니다.
- 같은 원본을 다시 편집할 예정이라면 spicy:// URI를 자체 레코드에 남기세요.
- invalid_asset은 장애가 아니라 사용자에게 보여줄 오류로 다루세요.
자주 묻는 질문
이 페이지에서 자주 나오는 질문
둘 다 됩니다. 공개적으로 접근 가능한 HTTPS 미디어 URL은 그대로 이미지 필드에 넣으면 됩니다. 업로드 티켓은 비공개 파일과 인라인 상한을 넘는 파일을 위한 것입니다.
장당 디코딩 후 1 MiB와 8,388,608 픽셀, 한 변 최대 8192 픽셀, 합계 최대 16장과 16,777,216 픽셀, 그리고 본문 전체 2 MiB입니다.
참조 검증은 접수 단계에서 이뤄집니다. 닿을 수 없는 호스트, 비공개 주소, 지원하지 않는 미디어 타입, 지나치게 큰 파일은 작업이 생기기 전에 400이나 413으로 실패하므로 보류도 과금도 없습니다.
엔드포인트에 따라 다릅니다. 동일성을 위한 참조 이미지 필드를 따로 선언한 엔드포인트도 있고, 무엇을 몇 장까지 받는지는 모델 페이지에 적혀 있습니다.
모델
이 작업에 바로 호출할 수 있는 모델
각 링크는 해당 모델 계열 페이지로 이동합니다. 입력, 상한, 콘텐츠 방침, 단위당 현재 가격을 그곳에서 확인할 수 있습니다.
다음
편집 엔드포인트 둘러보기
가진 사진과 지시문을 보내면 됩니다. 참조가 어떻게 들어가는지, 픽셀 상한은 얼마인지, 편집 엔드포인트는 무엇에 과금하는지.