비동기 생성이란
시간이 오래 걸리는 이미지 생성 요청의 경우, 플랫폼은 비동기 생성 모드를 지원합니다. 요청 제출 후 즉시 작업 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로 표시합니다