TokenLab의 GPT 이미지 편집 API: 올바른 엔드포인트 및 이미지 입력 형식

이미지 편집은 AI 제품 영역에서 까다로운 기능 중 하나입니다. 사용자가 사진을 업로드하고 변경 사항을 설명하면 즉각적인 결과를 기대하기 때문입니다. 여러 소스 이미지를 사용하거나, 캔버스가 크거나, 프롬프트가 복잡한 편집 작업은 일반적인 동기식 HTTP 호출이 안정적으로 감당할 수 있는 시간보다 오래 걸립니다. 이 가이드에서는 올바른 TokenLab 엔드포인트, 지원되는 두 가지 이미지 입력 형식, 다중 이미지 편집, 그리고 지연되는 요청을 처리하기 위한 비동기 경로를 다룹니다.

엔드포인트

이미지 편집 엔드포인트는 POST /v1/images/edits입니다. 복수형인 edits에 유의하세요. (자주 하는 실수 중 하나는 공식 문서에 없는 경로인 /images/edit로 작성하는 것입니다.)

이 엔드포인트는 두 가지 요청 형태를 지원합니다.

• OpenAI 호환 multipart/form-data 업로드 플로우.
• 지원되는 image-to-image 패밀리에 대해 image_url, image_urls 또는 공식 images[] 참조를 제공하는 JSON 요청.

전체 요청 및 응답 필드는 이미지 편집 API 레퍼런스에 설명되어 있습니다.

gpt-image-2가 지원하는 항목

• 멀티파트 image 업로드.
• JSON image_url 또는 image_urls.
• 각 객체에 image_url 또는 file_id 중 정확히 하나만 포함된 공식 images[] 참조.
• 요청당 최대 16개의 소스 이미지.

코드를 작성하기 전에 알아두어야 할 몇 가지 제약 사항:

• gpt-image-2 편집은 resolution을 허용하지 않습니다. 출력 치수에는 size를 사용하세요 (auto 또는 WIDTHxHEIGHT, 각 치수는 16의 배수여야 하며 가장 긴 변은 최대 3840px, 장축/단축 비율은 최대 3:1).
• background는 auto 또는 opaque를 허용하며, transparent는 지원되지 않습니다.
• input_fidelity는 gpt-image-2에서 지원되는 필드가 아닙니다. 이를 전송하면 400 unsupported_parameter가 반환됩니다.
• JSON 요청의 경우 image_url, image_urls, images 중 정확히 하나만 제공해야 합니다. 각 images[] 객체에는 image_url 또는 file_id 중 정확히 하나가 포함되어야 합니다. file_id 값은 먼저 /v1/files를 통해 생성해야 합니다.
• Nano Banana 참조 이미지 요청은 /v1/images/edits가 아니라 /v1/images/generations에서 operation: "image-to-image" 및 image_urls와 함께 사용해야 합니다.

멀티파트 업로드 vs JSON 이미지 참조

두 방식 모두 gpt-image-2에서 작동합니다. 이미지 바이트가 현재 어디에 저장되어 있는지에 따라 적합한 방식을 선택하세요.

멀티파트(Multipart) — 사용자 업로드나 생성된 에셋 등 애플리케이션에 파일이 있는 경우 이 방식을 사용하세요. 여러 소스를 전송하려면 image 필드를 반복하여 전달합니다. 파일은 PNG, JPEG 또는 WebP 형식이어야 하며, 각각 최대 50 MiB 이하여야 합니다.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

JSON 이미지 URL — 이미지가 이미 공개 URL에 있거나 이전 TokenLab 요청에서 이미지를 생성하여 이미 URL을 확보한 경우 이 방식을 사용하세요.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

원격 URL은 자격 증명이나 프래그먼트가 포함되지 않은 공개 http/https여야 하며, localhost, 사설 또는 예약된 IP 대역으로 확인되어서는 안 됩니다. TokenLab은 해당 바이트를 가져와 멀티파트 image 파트로 모델에 전달합니다. 이미지당 제한은 50 MiB이며, 단일 요청에서 URL로 가져오는 이미지의 총 합계 제한은 200 MiB입니다. 가져오기 타임아웃은 30초이고 최대 3번의 리디렉션이 허용됩니다.

다중 이미지 편집 및 비동기 폴링

다중 이미지 편집은 async: true를 사용해야 하는 가장 명확한 사례입니다. 복잡한 지시 세트와 함께 여러 이미지를 동기 호출로 전송하면 모델이 작업을 완료할 때까지 연결을 계속 열어두어야 합니다. gpt-image-2(및 공식 FLUX/BFL 편집 모델)에서 async: true를 설정하면 대신 작업(task)을 반환받을 수 있습니다:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

반환된 poll_url을 폴링하거나, GET /v1/tasks/{task_id}를 폴백으로 사용할 수 있습니다. 상태 값에는 pending, processing, completed, failed가 있습니다. 완료된 이미지 작업은 data[].url을 반환합니다. 3~5초마다 한 번씩 확인하는 것으로 충분하며, 계속 폴링하지 말고 최종 상태에 도달하면 폴링을 중단하세요.

curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"

비동기 편집 작업은 요청된 response_format과 상관없이 최종 이미지 URL을 반환합니다. 원시 b64_json이 필요한 경우 동기 요청을 사용하세요.

작업 생성 시 예상 금액이 가승인(예치)될 수 있습니다. 완료된 작업은 실제 사용량에 따라 청구되며, 실패하거나 타임아웃된 작업은 가승인이 해제되거나 환불됩니다. 전체 라이프사이클은 비동기 작업 및 폴링을 참조하고, 응답 필드는 이미지 상태 조회를 참조하세요.

각 모드를 사용하는 시점

다음의 경우 async: true를 사용하세요:

• 한 번의 요청에 여러 소스 이미지를 전송하는 경우.
• 프롬프트나 지시 세트가 복잡하여 생성 시간을 예측하기 어려운 경우.
• 실시간 사용자 대면 요청이 아닌 백그라운드 작업, 큐 또는 배치 프로세스에서 편집을 실행하는 경우.

다음의 경우 동기 방식을 유지하세요:

• 짧은 프롬프트로 단일 이미지를 편집하는 경우.
• 클라이언트가 폴링 대신 즉시 실패(fail-fast)하는 방식을 선호하는 경우.

동기 호출의 경우 HTTP 클라이언트 타임아웃을 최소 120s로 설정하세요. 고해상도 또는 고품질 요청은 1분 가까이 또는 그 이상 걸릴 수 있습니다. 생성 응답에 여전히 status: "pending", task_id 또는 poll_url이 포함되어 반환되면 제공된 폴링 플로우로 전환하세요.

예상되는 입력 오류

원격 이미지 가져오기 실패는 생성이 시작되기 전에 입력 오류로 반환됩니다. 접근할 수 없는 URL, 타임아웃, 403/404 응답, 사설 또는 내부 호스트, URL 내 자격 증명 또는 프래그먼트, 이미지가 아닌 콘텐츠, 지원되지 않는 형식, 크기 제한 위반 등은 400 또는 413을 반환하며 문제가 된 image_url 또는 image_urls[n]을 식별합니다. 비공개이거나 헤더 보호가 필요한 에셋의 경우 멀티파트 image 파일을 직접 업로드하거나 /v1/files 참조를 생성하여 images[].file_id로 전달하세요.

xAI Grok Imagine 이미지 편집 모델(예: grok-imagine-image 및 grok-imagine-image-quality)은 동일한 입력 필드를 사용하지만 소스 이미지를 최대 3개로 제한하며, 이를 초과하면 400 too_many_images가 반환됩니다.

연동 체크리스트

• POST /v1/images/edits를 대상으로 지정하고 model을 명시적으로 전송합니다.
• 이미지가 현재 저장되어 있는 위치에 따라 멀티파트 업로드 또는 JSON 참조를 선택합니다.
• JSON 요청에서는 image_url, image_urls, images[] 중 정확히 하나만 전송합니다. 각 images[] 항목에는 image_url 또는 file_id 중 정확히 하나가 포함되어야 합니다.
• 다중 이미지 또는 복잡한 편집 작업에는 async: true를 사용하고, 작업이 completed 또는 failed에 도달할 때까지 반환된 poll_url을 폴링합니다.
• 동기 요청의 경우 클라이언트 타임아웃을 최소 120초로 설정하고, pending 응답이 올 경우 poll_url을 따라 처리합니다.
• 클라이언트 타임아웃이 발생한 경우 중복 청구를 방지하기 위해 생성 요청을 재시도하기 전에 작업이 생성되었는지 확인합니다.

시작하기

GET /v1/models?recommended_for=image를 쿼리하여 현재 지원되는 이미지 모델을 확인한 다음, 요청을 보내기 전에 모델 세부 정보 페이지를 열어 지원되는 작업과 요청 필드를 확인하세요. 콘솔에서 API 키를 생성하고 보유한 이미지로 편집 엔드포인트를 테스트해보세요.