TokenLab

이미지

Edit Image

프롬프트와 소스 이미지를 기반으로 이미지를 편집합니다

POST
/v1/images/edits

개요

원본 이미지와 프롬프트를 기반으로 편집되거나 확장된 이미지를 생성합니다.

이 엔드포인트는 다음 두 가지 방식을 모두 지원합니다:

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

gpt-image-2가 지원됩니다. multipart image 업로드, JSON image_url / image_urls, 그리고 공식 images[] 참조(image_url 또는 file_id)를 지원하며 소스 이미지를 최대 16개까지 허용합니다. file_id 값은 먼저 /v1/files를 통해 생성하세요. 작업을 먼저 반환받으려면 async: true를 설정하세요. gpt-image-2 및 FLUX 편집 모델처럼 지원 파라미터에 async가 나열된 모든 모델은 동일한 작업 폴링 플로우를 사용합니다.

gpt-image-2 편집은 resolution을 허용하지 않습니다. 출력 치수에는 size를 사용하세요. background는 auto 또는 opaque를 허용하며, transparent는 지원되지 않습니다. 다중 이미지 또는 지연 시간이 긴 편집의 경우 async: true를 사용하고 반환된 작업을 폴링하는 것이 좋습니다.

Nano Banana 참조 이미지 요청(nano-banana-2, nano-banana-2.1, nano-banana-2-lite, nano-banana-pro)은 이 /v1/images/edits 엔드포인트가 아닌, operation: "image-to-image" 및 image_urls와 함께 /v1/images/generations에 노출됩니다. nano-banana-2, nano-banana-2.1, nano-banana-2-lite, nano-banana-pro에 대한 이미지 편집 요청 역시 operation: "image-edit"과 함께 /v1/images/generations를 사용합니다.

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image, gemini-3-pro-image는 이미지 편집에 이 엔드포인트를 사용합니다. 해당 모델들의 image-to-image 요청은 operation: "image-to-image"와 함께 /v1/images/generations를 사용합니다.

xAI Grok Imagine 이미지 편집 모델은 제한된 수의 소스 이미지를 허용합니다. grok-imagine-image-2.0은 최대 5개, grok-imagine-image는 최대 3개를 허용합니다. 모델이 허용하는 것보다 많은 소스 이미지를 포함한 요청은 400 too_many_images로 입력 유효성 검사에 실패합니다. 해당 모델들의 image-to-image 요청 또한 이 엔드포인트를 사용합니다.

각 모델의 상세 정보(GET /v1/models/{model}, Get Model 참조)는 tokenlab.request_format_summary.request_endpoint_by_operation에서 각 작업에 대한 엔드포인트를 제공하고, tokenlab.request_format_details.operation_constraints에서 허용되는 필드 및 제한 사항을 제공합니다. 잘못된 엔드포인트로 전송된 작업은 400 unsupported_endpoint를 반환합니다.

input_fidelity는 gpt-image-2에 대해 현재 TokenLab에서 지원하는 필드가 아닙니다. 생략해야 하며, 그렇지 않으면 요청 시 400 unsupported_parameter가 반환됩니다.

요청 본문

동기식 요청 타임아웃: 일부 이미지 요청은 최종 이미지를 인라인으로 반환하며 생성이 완료될 때까지 대기합니다. 고해상도 또는 고품질 요청은 1분 가까이 또는 그 이상 걸릴 수 있으므로 HTTP 클라이언트 타임아웃을 최소 120s로 설정하세요. 생성 응답에 status: "pending", task_id 또는 poll_url이 포함되어 있다면 대신 GET /v1/tasks/{task_id}를 폴링하세요.

원격 이미지 URL: multipart 입력이 필요한 경우, TokenLab은 JSON image_url, image_urls 또는 images[].image_url을 가져와 바이트를 multipart image 파트로 전송합니다. URL은 자격 증명이나 프래그먼트가 포함되지 않은 공개 http/https여야 하며, localhost, 프라이빗 또는 예약된 IP 범위로 확인되어서는 안 됩니다. 각 리디렉션은 다시 검사됩니다. 가져온 페이로드는 유효한 PNG, JPEG 또는 WebP 이미지여야 합니다. 제한은 이미지당 50 MiB, 한 요청에서 URL로 가져오는 이미지의 경우 총 200 MiB, 가져오기 타임아웃 30s, 최대 3회의 리디렉션입니다.

JSON 요청의 경우 image_url, image_urls, images 중 정확히 하나만 제공하세요. 각 images[] 객체는 image_url 또는 file_id 중 정확히 하나를 포함해야 합니다. 200 MiB의 총합 제한에는 모든 소스 이미지와 마스크가 포함됩니다.

imagefile

Multipart 소스 이미지입니다. 여러 개의 GPT Image 소스를 제공하려면 image를 반복하세요. 파일은 PNG, JPEG 또는 WebP 형식이어야 하며, 최대 16개의 소스 이미지와 각 50 MiB까지 허용됩니다. xAI Grok Imagine 편집 모델도 동일한 입력 필드를 사용하지만 소스 이미지가 제한됩니다. grok-imagine-image-2.0의 경우 최대 5개, 기타 xAI 편집 모델의 경우 최대 3개입니다.

promptstring필수

원하는 편집에 대한 텍스트 설명으로, 최대 32,000자입니다. 세부 정보에 prompt가 나열된 모든 모델에 필수입니다. stability-upscale-fast와 같이 프롬프트가 없는 도구는 프롬프트 없이 호출됩니다.

maskfile | object

완전히 투명한 영역을 통해 이미지가 편집되어야 할 위치를 나타내는 추가 이미지입니다. 유효한 PNG 파일이어야 하고 50 MiB 미만이어야 하며, image와 동일한 치수여야 합니다.

JSON 요청의 경우 mask는 image_url 또는 file_id 중 정확히 하나를 가진 객체일 수도 있습니다. file_id 값은 /v1/files에서 가져와야 하며 동일한 이미지 편집 구성에 바인딩된 상태로 유지되어야 합니다.

modelstring필수

이미지 편집에 사용할 모델입니다. GPT Image 편집에는 gpt-image-2를 사용하거나, GET /v1/models?recommended_for=image가 반환하는 다른 최신 이미지 편집 모델을 사용하세요.

ninteger기본값: 1

생성할 이미지 수입니다 (1-10, 모델에 따라 다름).

sizestring

생성된 이미지의 크기입니다. gpt-image-2의 경우 auto 또는 WIDTHxHEIGHT를 사용하세요. 치수는 16의 배수여야 하며, 가장 긴 변은 최대 3840px, 장축/단축 비율은 최대 3:1, 총 픽셀 수는 655,360에서 8,294,400 사이여야 합니다.

gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image, gemini-3.1-flash-lite-image의 경우 size는 모델의 크기 테이블에 있는 출력 크기 또는 해상도 티어(1K, 2K, 4K)를 허용합니다. TokenLab은 티어를 resolution으로 전송합니다. 모델이 지원하지 않는 티어이거나 resolution과 다른 티어인 경우 invalid_image_size_contract 코드와 함께 400을 반환합니다. 권장되는 형식은 resolution과 함께 aspect_ratio를 사용하는 것입니다.

response_formatstring

이미지가 반환되는 방식입니다: url 또는 b64_json.

  • 생략 시: 모델이 이미지 바이트를 반환할 때 각 이미지는 data[].b64_json에 포함되며, TokenLab이 저장한 경우 data[].url에도 포함됩니다. 모델이 링크를 반환할 때 각 이미지는 data[].url에 포함됩니다.
  • url: 각 이미지가 data[].url에만 포함됩니다.
  • b64_json: 각 이미지가 Base64 데이터로 data[].b64_json에만 포함됩니다.

링크는 TokenLab 미디어 결과 URL입니다. 30일 동안 유효하게 유지됩니다. 데이터 보존을 참조하세요.

asyncboolean기본값: false

최종 이미지가 준비되기 전에 작업을 반환받으려면 true로 설정하세요. gpt-image-2와 같이 지원 파라미터에 async가 나열된 모델만 이를 허용합니다. 다른 모델의 경우 요청 시 400 unsupported_async_mode가 반환됩니다. 완료된 비동기 편집은 요청된 response_format에 관계없이 URL을 반환합니다. b64_json이 필요한 경우 동기식 요청을 사용하세요.

userstring

어뷰징 모니터링을 위해 최종 사용자를 나타내는 고유 식별자입니다.

응답

createdinteger

이미지가 생성된 시점의 Unix 타임스탬프입니다.

dataarray

생성된 이미지의 배열입니다.

각 객체는 다음을 포함합니다:

  • url (string): 편집된 이미지의 TokenLab 미디어 결과 URL이며 30일 동안 유효합니다. response_format이 b64_json인 경우에는 존재하지 않습니다. response_format이 생략된 경우 TokenLab이 이미지를 저장할 수 없었다면 누락됩니다.
  • b64_json (string): Base64 이미지 데이터입니다. response_format이 b64_json이거나, 생략되었으며 모델이 이미지 바이트를 반환할 때 존재합니다.
usageobject

사용 가능한 경우, gpt-image-2와 같은 토큰 기반 가격 책정 모델에 대한 토큰 수(input_tokens, output_tokens, total_tokens 및 해당 세부 정보)입니다.

비동기 작업 응답

이를 지원하는 모델에서 async: true를 설정하면 요청에서 편집된 이미지를 기다리는 대신 작업을 생성합니다. 응답에는 status: "pending", task_id, poll_url이 포함됩니다. 작업이 completed 또는 failed에 도달할 때까지 /v1/tasks/{task_id}를 폴링하세요.

비동기 편집 작업은 최종 이미지 URL만 반환합니다. 원시 b64_json 이미지 데이터가 필요한 경우 동기식 요청을 사용하세요.

요금 청구는 작업이 생성될 때 예상 금액을 예약할 수 있습니다. 완료된 작업은 실제 사용량에 따라 청구되며, 실패하거나 타임아웃된 작업은 예약이 해제되거나 환불됩니다.

요청

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

응답

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

참고 사항

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

타임아웃 발생 후 안전하게 요청을 재시도하려면 Idempotency-Key 헤더를 전송하세요. 멱등성 키로 안전하게 재시도하기를 참조하세요.

Hy Image 3.5 Preview는 작성된 지침을 바탕으로 참조 이미지를 편집합니다. size는 1024x1024, n은 1만 허용합니다:

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

이미지 요청이 작업을 생성한 경우 안전하게 재시도할 수 있게 하는 선택적 키입니다. 각 요청마다 UUID와 같은 새로운 고유 값을 전송하십시오. 동일한 키와 동일한 본문으로 재시도하면 해당 작업이 반환되며, 두 번째 작업이 생성, 발송 또는 청구되지 않습니다. 이미지를 직접 반환하는 요청의 경우, 동일한 키로 재시도하면 이미지 대신 작업 상태가 반환되거나 idempotent_response_not_replayable과 함께 409가 반환될 수 있습니다. 이미 수락된 키와 다른 본문을 전송하면 거부되며, 이 경우의 상태 코드와 오류 코드는 보장되지 않습니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json