미디어 가이드
이미지 생성
이미지 생성 또는 편집, 완료된 파일 처리 및 비동기 작업 관리
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또는 JSONimages[]. - 모델이
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또는httpsURL이어야 합니다. 사설 네트워크 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 참조
| 주제 | 참조 |
|---|---|
| 이미지 생성 | 이미지 생성 |
| 이미지 편집 | 이미지 편집 |
| 이미지 변형 생성 | 이미지 변형 생성 |
| 이미지 상태 가져오기 | 이미지 상태 가져오기 |
| 작업 상태 가져오기 | 작업 상태 가져오기 |