이미지
이미지 편집 (Edit Image)
프롬프트와 원본 이미지를 사용하여 이미지를 편집합니다
개요
원본 이미지와 프롬프트를 입력받아 편집되거나 확장된 이미지를 생성합니다.
이 엔드포인트는 다음 두 가지 방식을 모두 지원합니다:
- 아래에 문서화된 OpenAI 호환
multipart/form-data업로드 방식 - 지원되는 이미지 간(image-to-image) 변환 모델을 위해
image_url,image_urls또는 공식images참조를 제공하는 JSON 요청 방식
gpt-image-2는 여기서 지원됩니다. 이 모델은 multipart image 업로드, JSON image_url / image_urls, 그리고 최대 16개의 소스 이미지를 포함하는 공식 images[] 참조(image_url 또는 file_id)를 허용합니다. file_id 값은 /v1/files를 통해 먼저 생성하십시오. 작업을 먼저 반환받으려면 async: true로 설정하십시오. 공식 FLUX/BFL 편집 모델도 동일한 작업 폴링(polling) 흐름을 사용합니다.
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는 이미지 편집을 위해 이 엔드포인트를 사용합니다. 이 모델들의 이미지 간 변환 요청은 operation: "image-to-image"와 함께 /v1/images/generations를 사용합니다.
xAI Grok Imagine 이미지 편집 모델이 허용하는 소스 이미지 수에는 제한이 있습니다. grok-imagine-image-2.0은 최대 5개, grok-imagine-image와 이전 버전인 grok-imagine-image-pro는 최대 3개입니다. 모델 한도를 초과하는 소스 이미지를 포함한 요청은 400 too_many_images와 함께 입력 검증에 실패합니다.
input_fidelity는 현재 gpt-image-2에 대해 TokenLab에서 지원하는 필드가 아닙니다. 이 필드를 생략하지 않으면 요청 시 400 unsupported_parameter가 반환됩니다.
요청 본문 (Request Body)
동기식 요청 타임아웃: 일부 이미지 요청은 최종 이미지를 인라인으로 반환하며 생성이 완료될 때까지 대기합니다. 고해상도 또는 고품질 요청은 1분 이상 소요될 수 있으므로, HTTP 클라이언트 타임아웃을 최소 120s로 설정하십시오. 생성 응답에 status: "pending", task_id 또는 poll_url이 포함된 경우, 반환된 poll_url을 따르십시오.
원격 이미지 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 총합 제한에는 모든 소스 이미지와 마스크가 포함됩니다.
Multipart 소스 이미지입니다. 여러 GPT Image 소스를 제공하려면 image를 반복하십시오. 파일은 PNG, JPEG 또는 WebP여야 하며, 최대 16개의 소스 이미지까지 가능하고 각 파일은 50 MiB 이하여야 합니다. xAI Grok Imagine 편집 모델은 동일한 입력 필드를 사용하지만 소스 이미지를 grok-imagine-image-2.0은 최대 5개, 다른 xAI 편집 모델은 최대 3개로 제한합니다.
원하는 편집에 대한 텍스트 설명입니다.
이미지에서 편집할 영역을 완전히 투명한 부분으로 표시하는 추가 이미지입니다. 유효한 PNG 파일이어야 하며, 50 MiB 미만이고 image와 동일한 크기여야 합니다.
JSON 요청의 경우, mask는 image_url 또는 file_id 중 하나만 포함하는 객체일 수도 있습니다. file_id 값은 /v1/files에서 가져와야 하며 동일한 이미지 편집 구성에 바인딩된 상태여야 합니다.
이미지 편집에 사용할 모델입니다. GPT Image 편집에는 gpt-image-2를 사용하거나, GET /v1/models?recommended_for=image에서 반환되는 다른 최신 이미지 편집 모델을 사용하십시오.
1생성할 이미지 수입니다(1-10, 모델에 따라 다름).
생성된 이미지의 크기입니다. 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와 같은 해상도 계층(tier)을 허용합니다. TokenLab은 계층을 resolution으로 전송합니다. 모델이 지원하지 않는 계층이거나 resolution과 다른 계층을 사용하면 400 코드와 함께 invalid_image_size_contract가 반환됩니다. 권장되는 형식은 aspect_ratio와 resolution을 함께 사용하는 것입니다.
이미지 반환 방식: url 또는 b64_json.
- 생략 시: 모델이 이미지 바이트를 반환하면 각 이미지는
data[].b64_json에 포함되며, TokenLab이 저장한 경우data[].url에도 포함됩니다. 모델이 링크를 반환하면 각 이미지는data[].url에 포함됩니다. url: 각 이미지는data[].url에만 포함됩니다.b64_json: 각 이미지는 Base64 데이터로서data[].b64_json에만 포함됩니다.
링크는 TokenLab 미디어 결과 URL입니다. 30일 동안 유효합니다. 데이터 보존을 참조하십시오.
falsegpt-image-2 또는 공식 FLUX/BFL 편집 모델과 함께 true로 설정하면 최종 이미지가 준비되기 전에 작업을 반환합니다. 완료된 비동기 편집은 요청된 response_format과 관계없이 URL을 반환합니다. b64_json이 필요한 경우 동기식 요청을 사용하십시오.
남용 모니터링을 위해 최종 사용자를 나타내는 고유 식별자입니다.
응답 (Response)
이미지가 생성된 Unix 타임스탬프입니다.
생성된 이미지 배열입니다.
각 객체는 다음을 포함합니다:
url(string): 편집된 이미지의 TokenLab 미디어 결과 URL이며, 30일 동안 유효합니다.response_format이b64_json인 경우에는 존재하지 않습니다.response_format이 생략된 경우, TokenLab이 이미지를 저장할 수 없었다면 이 필드는 누락됩니다.b64_json(string): Base64 이미지 데이터입니다.response_format이b64_json이거나, 생략되었는데 모델이 이미지 바이트를 반환한 경우에 존재합니다.
비동기 작업 응답 (Async Task Response)
gpt-image-2 또는 공식 FLUX/BFL 편집 모델과 함께 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"응답
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}참고 사항
원격 이미지 가져오기 실패는 생성 시작 전 입력 오류로 반환됩니다. 연결할 수 없는 URL, 타임아웃, 403/404 응답, 사설/내부 호스트, URL 내 자격 증명이나 프래그먼트, 이미지 형식이 아닌 콘텐츠, 지원되지 않는 형식, 크기 제한 위반은 400 또는 413을 반환하며 image_url / image_urls[n] 입력을 식별합니다. 사설 자산이나 헤더로 보호된 자산의 경우, multipart image 파일을 직접 업로드하거나 /v1/files 참조를 생성하십시오.
Hy Image 3.5 Preview는 텍스트로부터 1024픽셀 정사각형 이미지를 생성하고, 서면 지침을 사용하여 참조 이미지를 편집합니다. 시각 자료를 초안 작성하거나 구성을 다듬는 데 유용합니다.
{
"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 API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.
위치: header
헤더
요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.
허용 값
- "auto"
- "verified"
- "official"
응답
application/json
application/json
application/json
application/json
application/json
application/json