비동기 이미지 생성

비동기 생성이란

시간이 오래 걸리는 이미지 생성 요청의 경우, 플랫폼은 비동기 생성 모드를 지원합니다. 요청 제출 후 즉시 작업 ID를 반환하며, 클라이언트는 폴링으로 최종 결과를 가져옵니다. 긴 연결을 유지할 필요가 없습니다.

비동기 모드는 생성 시간이 긴 시나리오에 적합하며 요청 타임아웃 중단을 방지합니다. 여러 작업을 일괄 제출하기에도 편리합니다.

사용 흐름

비동기 생성은 3단계: 작업 제출 → 상태 폴링 → 결과 다운로드.

1. 작업 제출

https://api.tvtapi.com/v1/images/async로 POST 요청을 보내고 API Key(Bearer 인증)와 요청 매개변수를 포함합니다:

curl -X POST https://api.tvtapi.com/v1/images/async \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","prompt":"설명 텍스트"}'

응답에 task_id가 포함됩니다. 이것이 이후 조회 및 다운로드의 유일한 증명입니다.

2. 상태 폴링

task_id로 작업 상태를 폴링:

curl https://api.tvtapi.com/v1/images/async/{task_id} \
  -H "Authorization: Bearer sk-xxxxxxxx"

작업 상태: queued(대기 중), in_progress(생성 중), succeeded(성공), failed(실패). 몇 초 간격으로 폴링하며 상태가 succeeded 또는 failed가 될 때까지 반복합니다.

3. 이미지 다운로드

작업 성공 후 다음 주소로 이미지를 가져옵니다:

curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
  -H "Authorization: Bearer sk-xxxxxxxx"

이 엔드포인트는 이미지의 실제 저장 주소로 302 리디렉션을 반환합니다. 각 이미지에는 다운로드 횟수 제한이 있으며, 타임아웃 후 작업이 자동으로 만료됩니다.

웹에서도 사용 가능

코드를 작성하고 싶지 않다면 /ko-kr/user/image-studio의 이미지 워크벤치를 직접 사용할 수 있습니다. 워크벤치에 비동기 모드 토글이 내장되어 있어, 켜면 페이지 내에서 자동으로 폴링하고 결과를 표시합니다.

주의 사항

  • 비동기 기능은 관리자가 백엔드에서 활성화해야 하며, 사용자 계정에 해당 권한이 필요합니다
  • 작업에는 유효 기간이 있으며, 만료 후 다운로드할 수 없습니다
  • 오랫동안 in_progress 상태가 지속되면 시스템이 자동으로 타임아웃하고 failed로 표시합니다