TokenLab

미디어 가이드

이미지 생성

이미지 생성 또는 편집, 완료된 파일 처리 및 비동기 작업 관리

TokenLab은 텍스트-투-이미지(text-to-image), 이미지-투-이미지(image-to-image) 및 이미지 편집을 지원합니다. 매개변수는 모델마다 다르므로, 요청을 보내기 전에 선택한 모델의 요청 필드를 확인하십시오.

엔드포인트 선택

필요한 작업엔드포인트사용 시기사용하지 말아야 할 때
텍스트-투-이미지POST /v1/images/generations사용자가 텍스트로 시작하는 경우기존 GPT Image 파일 편집
이미지-투-이미지POST /v1/images/generations모델이 operation: "image-to-image" 및 이미지 URL을 허용하는 경우멀티파트 편집 입력이 필요한 모델
이미지 편집POST /v1/images/edits지원되는 편집 모델이 기존 이미지를 변경하는 경우Nano Banana 스타일의 참조 생성
변형POST /v1/images/variations기존 통합에서 이미 variations API를 사용하는 경우새로운 참조 이미지 기능
상태 확인GET /v1/tasks/{id}생성 응답이 task_id, status: "pending" 또는 poll_url을 반환하는 경우생성 응답에 이미 최종 data[]가 포함된 경우

항상 model을 전송하십시오. 이미지 API는 기본 모델을 자동으로 선택하지 않습니다.

모델 선택

현재 이미지 모델을 찾으려면 다음을 사용하십시오:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

선택한 모델의 세부 정보를 열어 다음을 확인하십시오:

  • text-to-image, image-to-image 또는 image-edit와 같은 지원되는 작업.
  • 모델이 예상하는 요청 엔드포인트.
  • 참조 전달 방법: image_url, image_urls, reference_image_urls, 멀티파트 image 또는 JSON images[].
  • 모델이 size, aspect_ratio, resolution, quality, background, output_format 또는 response_format을 허용하는지 여부.

모델별 필드

  • gpt-image-2 스타일 요청은 OpenAI와 유사한 size, quality 및 편집 필드를 사용합니다. 이 모델을 사용한 생성 및 편집 시 background는 auto 또는 opaque를 허용하며, transparent는 지원되지 않습니다. 자동 기본값을 사용하려면 선택적 필드를 생략하십시오.
  • Gemini 및 Nano Banana 이미지 제품군은 일반적으로 aspect_ratio를 사용합니다. 모델 세부 정보에 명시된 경우에만 resolution을 전송하십시오. 해상도 계층이 있는 모델의 경우 1K, 2K 또는 4K의 size가 resolution으로 전송됩니다. resolution과 다른 계층은 거부됩니다.
  • Nano Banana 이미지-투-이미지는 operation: "image-to-image" 및 참조 이미지 URL과 함께 /v1/images/generations를 사용해야 합니다.
  • /v1/images/generations는 최상위 images[] 또는 file_id를 허용하지 않습니다. 이는 편집 흐름(edit-flow) 형태입니다.
  • 원격 이미지 참조는 공개 http 또는 https URL이어야 합니다. 사설 네트워크 URL, 포함된 자격 증명, URL 프래그먼트 또는 처리가 시작되기 전에 만료될 수 있는 서명된 URL은 전송하지 마십시오.

텍스트-투-이미지 예시

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a ceramic coffee cup on a walnut desk",
    "size": "1024x1024",
    "response_format": "url"
  }'

참조 이미지 예시

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

이미지 가져오기

이미지 응답은 동기식 또는 비동기식일 수 있습니다:

  • 동기식 응답은 url 또는 b64_json이 포함된 최종 data[]를 반환합니다.
  • 비동기식 응답은 id, task_id, status 및 일반적으로 poll_url을 반환합니다. 이미지를 기다리는 대신 작업을 가져오려면 공개 비동기 실행을 지원하는 모델에서 "async": true를 전송하십시오.
  • 비동기 작업을 확인하려면 반환된 id 또는 task_id와 함께 GET /v1/tasks/{id}를 호출하십시오.
  • b64_json이 필요한 경우 동기식 요청을 사용하십시오. 비동기 이미지 결과는 URL을 사용합니다.

이미지 결과 URL은 30일 동안 유효한 TokenLab 미디어 결과 URL입니다. media_retention.items는 각 항목의 저장 상태와 expires_at을 보고합니다. 저장 상태를 제때 알 수 없는 경우 응답에서 media_retention이 생략될 수 있으며, URL은 여전히 작동합니다. 인라인 Base64 결과는 이 URL 복사 보존 범위에 포함되지 않습니다. 이미지를 미디어 라이브러리에 수동으로 저장하면 별도의 수명 주기가 부여됩니다. 데이터 보존을 참조하십시오.

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

반환된 이미지 URL, 작업 ID, 모델 및 사용자/작업 ID를 유지하십시오. 최종 상태에 도달한 후에는 폴링을 중단하십시오.

출시 전 확인 사항

  • TokenLab을 호출하기 전에 프롬프트 길이, 이미지 개수, URL 도달 가능성 및 파일 유형과 같은 사용자 입력을 검증하십시오.
  • 동기식 고해상도 요청을 위해 HTTP 타임아웃을 충분히 길게 설정하십시오. 작업 시간이 긴 경우 모델이 지원하는 곳에서 async: true를 사용하십시오.
  • request_id, task_id, poll_url, 모델, 엔드포인트 및 전송된 필드 이름을 저장하십시오.
  • 이미지 요청이 작업을 반환할 때 Idempotency-Key를 사용하면 생성 요청을 안전하게 재시도할 수 있습니다. 클라이언트 타임아웃 후 동일한 키로 동일한 요청을 보내 해당 작업을 가져오십시오. 이미지를 직접 반환하는 요청의 경우, 동일한 키로 재시도하면 이미지 대신 작업 상태가 반환되거나 idempotent_response_not_replayable과 함께 409 오류가 발생할 수 있습니다. 키가 없는 경우 재시도하기 전에 작업이 생성되었는지 확인하십시오.
  • 최종 청구 금액은 사용량(Usage) 및 billing_transaction_id를 사용하십시오.

일반적인 오류

증상예상 원인해결 방법
400 오류 (param: "model")명시적 모델 누락/v1/models?recommended_for=image를 쿼리하고 model을 전송하십시오
지원되지 않는 필드해당 모델에 문서화되지 않은 필드필드를 제거하거나 해당 필드를 문서화하는 모델/엔드포인트를 선택하십시오
비동기 결과에 b64_json 없음비동기 이미지 작업은 URL 기반 결과를 반환함Base64 출력을 위해 동기식 모드를 사용하십시오
참조 이미지 거부됨잘못된 엔드포인트 또는 사설/만료된 URL모델의 문서화된 참조 형태와 일치시키고 도달 가능한 URL을 사용하십시오

API 참조

주제참조
이미지 생성이미지 생성
이미지 편집이미지 편집
이미지 변형 생성이미지 변형 생성
이미지 상태 가져오기이미지 상태 가져오기
작업 상태 가져오기작업 상태 가져오기

이 페이지의 내용