이미지 생성

TokenLab은 공용 이미지 엔드포인트를 통해 텍스트-투-이미지, 이미지-투-이미지 및 이미지 편집을 지원합니다. 이미지 모델은 하나의 보편적인 매개변수 집합을 공유하지 않으므로, 프로덕션 클라이언트는 먼저 엔드포인트를 선택한 다음 모델을 선택하고, 해당 모델에서 지원하는 필드만 전송해야 합니다.

각 엔드포인트 사용 시기

사용자 워크플로우	엔드포인트	사용 시	피해야 할 시
텍스트-투-이미지	`POST /v1/images/generations`	사용자가 프롬프트만으로 시작할 때	공식 GPT 이미지 편집 흐름이 필요할 때
이미지-투-이미지	`POST /v1/images/generations`	모델 문서가 `operation: "image-to-image"`와 `image_url`, `image_urls`, 또는 `reference_image_urls`를 통해 참조 이미지를 문서화할 때	모델이 멀티파트 편집 입력을 기대할 때
이미지 편집	`POST /v1/images/edits`	GPT 이미지 패밀리 모델과 같은 지원되는 편집 모델로 기존 이미지를 편집할 때	나노 바나나 스타일의 이미지-투-이미지 생성을 사용할 때
변형	`POST /v1/images/variations`	레거시 변형 호환 통합을 유지할 때	새로운 참조 이미지 워크플로우를 구축할 때
상태	`GET /v1/tasks/{id}`	생성 응답이 `task_id`, `status: "pending"`, 또는 `poll_url`을 반환할 때	생성 응답이 이미 최종 `data[]`를 포함할 때

항상 model을 전송하십시오. 이미지 엔드포인트는 의도적으로 프로덕션 트래픽에 대한 역사적 암묵적 기본 모델에 의존하지 않습니다.

모델 선택

모델 발견으로 시작한 다음 선택한 모델의 TokenLab 계약을 검사하십시오:

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

비채팅 모델의 경우, 목록 응답에는 GET /v1/models가 포함될 수 있습니다. 모델 세부 페이지는 더 완전한 GET /v1/models/{model}를 노출할 수 있습니다. 이러한 필드를 사용하여 확인하십시오:

지원되는 작업, 예를 들어 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 는 지원하지 않습니다. 모델이나 TokenLab이 자동 기본값을 사용하도록 하려면 선택적 필드를 생략하십시오.
제미니 및 나노 바나나 이미지 패밀리는 일반적으로 aspect_ratio를 사용합니다; 모델 계약이 이를 노출할 때만 resolution을 전송하십시오.
나노 바나나 이미지-투-이미지는 /v1/images/generations에서 operation: "image-to-image" 및 참조 이미지 URL과 함께 사용해야 합니다.
/v1/images/generations는 최상위 images[] 또는 file_id를 수용하지 않습니다; 이는 편집 흐름 형식입니다.
원격 이미지 참조는 공개 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": "호두 나무 책상 위에 있는 세라믹 커피 컵의 깔끔한 제품 사진",
    "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",
    "operation": "image-to-image",
    "prompt": "제품 모양을 유지하고 배경을 밝은 스튜디오 설정으로 변경",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

결과 처리

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

동기 응답은 최종 data[]를 url 또는 b64_json과 함께 반환합니다.
비동기 응답은 id, task_id, status, 및 일반적으로 poll_url을 반환합니다.
poll_url이 있을 때 이를 선호하십시오. 고정 경로가 필요하면 GET /v1/tasks/{id}를 폴링하십시오.
b64_json이 필요할 때는 동기 요청을 사용하십시오; 비동기 이미지 결과는 URL 지향적입니다.

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

반환된 이미지 URL, 작업 ID, 모델 및 귀하의 사용자/작업 ID를 유지하십시오. 최종 상태 이후에는 계속 폴링하지 마십시오.

프로덕션 체크리스트

TokenLab을 호출하기 전에 사용자 입력을 검증하십시오: 프롬프트 길이, 이미지 수, URL 도달 가능성, 및 파일 유형.
동기 고해상도 요청을 위해 HTTP 타임아웃을 충분히 높게 설정하십시오. 긴 작업을 위해 사용 가능한 경우 비동기 모드를 사용하십시오.
지원을 위해 request_id, task_id, poll_url, 모델, 엔드포인트, 및 정제된 요청 형식을 저장하십시오.
클라이언트 타임아웃 시, 생성 요청을 재시도하기 전에 작업이 생성되었는지 확인하십시오.
제공자 작업 ID가 아닌 사용 기록 및 billing_transaction_id와 비용을 조정하십시오.

일반적인 오류

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

API 참조

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

시작하기

핵심 가이드

미디어 가이드

각 엔드포인트 사용 시기

모델 선택

요청 형식 규칙

텍스트-투-이미지 예제

참조 이미지 예제

결과 처리

프로덕션 체크리스트

일반적인 오류

API 참조

​각 엔드포인트 사용 시기

​모델 선택

​요청 형식 규칙

​텍스트-투-이미지 예제

​참조 이미지 예제

​결과 처리

​프로덕션 체크리스트

​일반적인 오류

​API 참조

각 엔드포인트 사용 시기

모델 선택

요청 형식 규칙

텍스트-투-이미지 예제

참조 이미지 예제

결과 처리

프로덕션 체크리스트

일반적인 오류

API 참조