이미지 편집
이미지 API로 이미지 편집, 마스크 인페인팅, 변형 생성을 수행합니다.
개요
이미지 API는 기존 이미지를 세 가지 방식으로 편집합니다: 전체 이미지 편집, 마스크 기반 인페인팅, 변형. 모든 모드는 소스 이미지(및 선택적 마스크)를 업로드된 자료로 받습니다 — URL 경로도 인라인 경로도 없습니다.
경고
/v1/images/edits와 /v1/images/variations는 application/json만 받습니다. 레거시 multipart/form-data 파일 업로드는 제거되었으며 — multipart를 보내면 415 legacy_multipart_removed를 반환합니다. 이미지가 몇 KB이든 25 MB이든, 소스와 마스크는 먼저 사전 서명 업로드를 거친 다음 image_upload_id / mask_upload_id와 함께 JSON을 제출해야 합니다.
세 가지 모드
| 모드 | 엔드포인트 | 필수 | 효과 |
|---|---|---|---|
| 전체 이미지 편집 | POST /v1/images/edits | model, prompt, image_upload_id | 프롬프트에 따라 전체 이미지를 편집 |
| 마스크 인페인팅 | POST /v1/images/edits | 위 항목 + mask_upload_id | 마스크로 지정한 영역만 변경 |
| 변형 | POST /v1/images/variations | model, image_upload_id (prompt 불필요) | 같은 스타일의 변형 생성 |
mask_upload_id를 전달하면 편집이 자동으로 인페인팅으로 전환됩니다 — 별도의 플래그가 필요 없습니다.
이미지 편집하기
먼저 소스를 purpose=image_edit_source로 사전 서명 후 업로드합니다(인페인팅의 경우 마스크는 purpose=image_edit_mask로). 그런 다음 JSON을 제출합니다:
| 1 | curl https://api.alltoken.ai/v1/images/edits -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "prompt": "배경을 노을로 바꿔줘", |
| 4 | "image_upload_id": "upl_source...", |
| 5 | "mask_upload_id": "upl_mask...", |
| 6 | "size": "1024x1024", |
| 7 | "output_format": "png" |
| 8 | }' |
자주 쓰는 선택 필드: size, quality, output_format, output_compression, background, moderation, n, user. 전체 목록은 이미지 API 참조를 확인하세요.
변형 생성
변형은 소스 하나만 있으면 됩니다(purpose=image_variation_source로 업로드) — prompt 불필요:
| 1 | curl https://api.alltoken.ai/v1/images/variations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{ |
| 2 | "model": "gpt-image-1.5", |
| 3 | "image_upload_id": "upl_source...", |
| 4 | "n": 2 |
| 5 | }' |
선택 필드: size, n, output_compression, user.
결과 가져오기
생성 시 202 + { id, status: "queued", ... }를 반환합니다. 세 모드 모두 동일한 엔드포인트를 폴링합니다:
$curl https://api.alltoken.ai/v1/images/generations/{id} -H "Authorization: Bearer $ALLTOKEN_API_KEY"queued / processing 동안에는 응답에 next_poll_after_ms가 포함됩니다 — 이를 이용해 다음 폴링 간격을 조절하세요. completed가 되면 각 data[] 항목에 b64_json, r2_url, r2_url_expires_at, mime_type, revised_prompt가 담깁니다.
경고
b64_json은 한 번만 전달됩니다 — 첫 번째 completed GET에서만 반환되므로 즉시 디스크에 기록하세요. r2_url(30일 유효, 여러 기기에서 접근 가능)을 우선 사용하고 b64_json은 최초 수신 시의 대비책으로 취급하세요. r2_url이 만료되면 GET은 410 image_expired를 반환합니다. "이미지 목록" 엔드포인트는 없으므로 — 결과는 task_id로 직접 기록하세요.
배치 편집
한 요청은 소스 이미지 한 장(및 선택적 마스크 한 장)을 처리합니다. N장을 편집하려면 독립적인 3단계 흐름을 N번 실행하세요 — 각각 자체 presign → PUT → 생성 → 폴링을 거칩니다. 동시에 실행할 수 있으며, 두 가지 한도에 유의하세요:
- pending 업로드 100개 — 수백 개의
upload_id를 presign해 놓고 쓰지 않는 일이 없도록 하세요. - UTC 하루당 2 GiB — 25 MiB 파일 약 80장이면 상한에 도달합니다.
권장: 동시 5~10 레인을 유지하며, 각 레인이 다음 이미지를 가져가기 전에 완전한 presign → PUT → 생성 → 폴링을 실행하도록 하세요. 그러면 pending 수가 작게 유지되고 쿼터에 절대 닿지 않습니다. 쿼터 세부 사항은 미디어 업로드를 참조하세요.