비동기 작업 및 폴링

많은 미디어 엔드포인트는 비동기입니다. 생성 요청은 작업을 시작하고 공개 TokenLab 작업 ID를 반환합니다. 애플리케이션은 해당 작업이 최종 상태에 도달할 때까지 폴링합니다. 고객 워크플로우를 업스트림 작업 URL, 라우팅 ID 또는 공급자 콜백 동작을 기반으로 구축하지 마십시오.

공개 작업 계약

생성 응답에는 다음이 포함될 수 있습니다:

필드	의미	수행할 작업
`id`	공개 TokenLab 작업 ID	자신의 작업 기록과 함께 저장합니다
`task_id`	동일한 공개 작업 ID에 대한 호환성 별칭	`id`와 동등하게 취급합니다
`status`	현재 공개 작업 상태	최종 상태가 아닐 때 폴링을 시작합니다
`poll_url`	선호하는 상태 URL	존재할 경우 이를 먼저 사용합니다
`model`	엔드포인트에서 요청되거나 해결된 모델	지원 및 청구 조정을 위해 저장합니다

/v1/tasks/{id}는 공개 비동기 미디어 작업에 대한 표준 고정 상태 엔드포인트입니다. 호환성을 위해 미디어 특정 상태 경로가 존재할 수 있지만, 새로운 통합은 poll_url 또는 /v1/tasks/{id}를 선호해야 합니다.

권장 흐름

사용자 요청을 검증하고 명시적인 model과 함께 생성 호출을 보냅니다.
UI에 제어를 반환하기 전에 id / task_id, poll_url, 엔드포인트, 모델, 사용자 ID 및 자신의 작업 ID를 저장합니다.
장기 실행 미디어 작업에 대해 매 5-10초마다 폴링합니다.
작업이 completed 또는 failed일 때만 중지합니다.
completed 시, 미디어 특정 결과 필드를 읽고 최종 URL 또는 메타데이터를 저장합니다.
failed 시, 공개 오류를 저장하고 새 사용자 가시 작업으로만 재시도를 제공합니다.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

폴링 예제

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

예상되는 공개 상태는 pending, processing, completed, 및 failed입니다. 취소된 작업은 failed로 표시되며 cancelled: true 및 cancellation_status: "cancelled"로 나타나므로 이전 상태 처리가 계속 작동합니다.

클라이언트 재시도 규칙

네트워크 타임아웃은 중복 작업의 가장 일반적인 원인입니다. 이 규칙을 사용하십시오:

타임아웃 발생 위치	더 안전한 동작
서버가 생성 응답을 받기 전	`request_id`에 대한 서버 로그를 확인; 작업이 생성되지 않은 경우에만 재시도
생성 응답이 저장된 후	저장된 `task_id`에 대한 폴링을 재개
폴링 중	백오프와 함께 상태 요청을 재시도
최종 상태 이후	사용자가 명시적으로 레코드를 새로 고치지 않는 한 다시 폴링하지 않음

브라우저가 새로 고쳐지거나 상태 폴링이 실패했다고 해서 두 번째 생성 요청을 보내지 마십시오.

청구 및 정산

비동기 작업은 생성 요청이 수락될 때 예상 금액을 예약할 수 있습니다. 최종 정산은 최종 상태 이후에 발생합니다. 사용 가능한 경우, 작업 상태 응답은 billing_transaction_id 및 X-Billing-Transaction-ID 헤더를 노출할 수 있습니다. 조정을 위해, 로그에서 다음 식별자를 결합하십시오:

생성 요청의 request_id.
작업의 task_id / id.
존재할 경우 billing_transaction_id.
자신의 사용자 ID, 프로젝트 ID 또는 작업 ID.

취소

DELETE /v1/tasks/{id}는 의도적으로 좁습니다. 현재 seedance-1.5-pro, seedance-2.0, 및 seedance-2.0-fast와 같은 대기 중인 Volcengine Seedance 비디오 작업을 지원합니다. 지원되지 않는 작업은 400 unsupported_task_cancel을 반환합니다. 이미 실행 중이거나 최종 상태인 작업은 409 task_not_cancellable을 반환합니다. 취소 UI를 “취소 요청”으로 구축하고 보장된 중지 버튼으로 만들지 마십시오.

문제 해결

증상	가능한 원인	확인할 사항
`async_task_not_found`	작업이 알려지지 않거나, 만료되었거나, 이 API 키에 접근할 수 없거나, 공개 비동기 작업이 아님	API 키 소유권 및 저장된 공개 `task_id`를 확인
작업이 완료되지 않음	클라이언트가 잘못된 URL을 계속 폴링하거나 최종 상태 이전에 중지됨	`poll_url` 또는 `/v1/tasks/{id}`를 사용하고 최신 상태를 검사
최종 미디어 URL 누락	작업이 완료되지 않았거나, 업스트림 작업이 사용 가능한 출력 없이 완료됨	최종 상태까지 계속 폴링한 후 누락된 출력을 실패로 처리
사용자가 중복을 봄	재시도 경로가 타임아웃 또는 새로 고침 후 새 작업을 생성함	자신의 작업 ID 및 저장된 `task_id`로 중복 제거
청구 불일치	정산이 비동기이거나 클라이언트가 공급자 ID를 비교 중임	`request_id`, `task_id`, 및 `billing_transaction_id`를 비교

지원 패킷

지원에 연락할 때는 request_id, task_id, 존재할 경우 billing_transaction_id, 엔드포인트, 모델, 타임스탬프 및 정리된 요청 형식을 포함하십시오. 지원에서 수정된 샘플을 요청하지 않는 한 API 키, 개인 미디어, 서명된 URL 또는 전체 프롬프트를 포함하지 마십시오.

API 참조

주제	참조
작업 상태 가져오기	작업 상태 가져오기
작업 취소	작업 취소
이미지 생성	이미지 생성
비디오 생성	비디오 생성
음악 생성	음악 생성
3D 생성	3D 생성
청구 및 가격 책정	청구 및 가격 책정

​공개 작업 계약

​권장 흐름

​폴링 예제

​클라이언트 재시도 규칙

​청구 및 정산

​취소

​문제 해결

​지원 패킷

​API 참조