TokenLab

핵심 가이드

비동기 작업 및 폴링

미디어 작업을 생성하고 완료된 결과를 기다리는 방법

많은 미디어 엔드포인트는 완료된 파일 대신 작업을 반환합니다. 반환된 작업 ID를 저장하고 상태가 completed 또는 failed가 될 때까지 GET /v1/tasks/{id}를 폴링하십시오. 이 단일 엔드포인트는 이미지, 비디오, 음악, 3D, Worlds 및 비동기 오디오 전사 작업을 처리합니다.

비동기 터미널 작업 스냅샷은 30일간의 요청/응답 캡처 기간과는 별도의 수명 주기를 가집니다. 생성된 이미지, 비디오, 오디오, 3D 및 Worlds 파일 URL은 30일 동안 유효한 TokenLab 미디어 결과 URL입니다. 완료된 작업의 상태 조회는 약 7일 동안 작동하므로, 작업이 완료되는 즉시 결과를 저장하십시오. 응답의 media_retention 필드는 각 항목의 저장 상태와 expires_at을 보고합니다. 저장 상태를 제때 알 수 없는 경우 이 필드가 없을 수 있으며, URL은 여전히 작동합니다. 실패했거나 진행 중인 작업은 빈 미디어 URL 필드를 반환합니다. 데이터 보존을 참조하십시오.

저장해야 할 필드

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

필드의미수행할 작업
idTokenLab 작업 ID자체 작업 기록과 함께 저장
task_id동일한 작업 ID의 다른 명칭id와 동일하게 취급
status현재 작업 상태완료되거나 실패할 때까지 계속 확인
poll_url작업 상태 URL저장; 작업 ID를 사용하여 /v1/tasks/{id} 폴링
model작업에 사용된 모델작업 기록과 함께 저장

단일 상태 엔드포인트

생성 응답의 id 또는 task_id를 사용하여 GET /v1/tasks/{id}를 폴링하십시오. 이는 모든 작업 유형에 작동합니다. 대부분의 작업에서 poll_url은 이와 동일한 경로입니다. Worlds 생성 응답은 /v1/worlds/generations/{id} 하위의 poll_url을 반환하지만, Worlds 작업의 경우에도 작업 id를 사용하여 /v1/tasks/{id}를 폴링하십시오.

/v1/videos/generations/{id}와 같은 모달리티별 상태 경로는 기존 통합을 위해 계속 지원됩니다. 새로운 통합은 /v1/tasks/{id}를 사용해야 합니다.

작업 저장 및 상태 확인

생성 요청이 성공하는 즉시 id 또는 task_id를 저장하십시오. poll_url, 모델, 엔드포인트 및 자체 사용자 또는 작업 ID를 함께 저장하십시오. 긴 미디어 작업의 경우 5~10초마다 확인하는 것으로 충분합니다.

상태가 completed 또는 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"를 사용합니다.

성공적인 상태 조회는 작업이 실패했더라도 HTTP 200을 반환합니다. 작업의 status를 사용하여 생성이 성공했는지 여부를 결정하십시오. error 필드는 문자열 또는 객체 형태를 유지합니다. 실패한 작업에는 status(비즈니스 오류 상태), type, code, message, param 및 retryable을 포함하는 error_details가 포함될 수 있습니다. 예를 들어, error_details.status: 400과 param: "size"는 요청에 수정이 필요함을 의미하며, 상태 요청 자체가 실패했음을 의미하지는 않습니다. 특정 필드를 알 수 없는 경우 param은 생략됩니다. error_details.projection_version이 2인 경우, message는 실패의 최종 원인이며, 일반적으로 매개변수 제한이나 콘텐츠 정책 결정과 같은 업스트림 서비스의 자체 설명입니다. Official 경로에서 실행된 작업의 경우, error_details.upstream은 보고된 업스트림 오류(message와 함께 알려진 경우 code, param, source(업스트림 서비스 이름))를 전달합니다. code 및 type에 따라 분기 처리를 유지하십시오. upstream.code 값은 업스트림 서비스에 의해 정의되며 변경될 수 있습니다.

작업이 수락되기 전에 생성 요청을 거부하는 오류는 일반적인 HTTP 오류 상태와 구조화된 error 객체를 사용합니다. 동일한 멱등성(idempotent) 생성 요청을 반복하면 해당 거부 상태가 유지됩니다. 실패한 상태 조회는 작업의 터미널 상태를 변경하지 않습니다.

중복 작업 방지

대부분의 중복 생성은 타임아웃 후 생성 요청을 재시도할 때 발생합니다.

타임아웃 발생 시점권장 동작
서버가 생성 응답을 받기 전동일한 Idempotency-Key를 사용하여 동일한 요청을 다시 보내 원래 작업을 가져옵니다. 키가 없는 경우 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-2.0 및 seedance-2.0-fast를 포함하여 큐에 대기 중인 지원되는 Seedance 비디오 작업을 취소할 수 있습니다.

지원되지 않는 작업은 400 unsupported_task_cancel을 반환합니다. 이미 실행 중이거나 완료된 작업은 409 task_not_cancellable을 반환합니다. 취소는 요청일 뿐이며, 이미 진행 중인 작업이 즉시 중단된다는 보장은 없습니다. 성공적인 취소는 200과 함께 status: "failed", cancelled: true, cancellation_status: "cancelled"를 반환합니다. 취소된 작업은 청구되지 않습니다.

문제 해결

증상가능한 원인확인 사항
404 async_task_not_found작업 ID를 알 수 없거나, 다른 워크스페이스에 속해 있거나, 완료된 작업이 상태 조회 기간을 지남저장된 task_id와 API 키의 워크스페이스 확인
403 task_not_owned현재 워크스페이스에 대한 작업 소유권을 확인할 수 없음API 키와 연결된 워크스페이스 또는 조직 확인
503 async_task_owner_unavailable현재 작업 소유권을 확인할 수 없음. retryable은 true임백오프를 사용하여 상태 요청 재시도
작업이 완료되지 않음클라이언트가 잘못된 URL을 계속 폴링하거나 터미널 상태 전에 중단함저장된 작업 ID로 GET /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 생성
청구 및 가격 책정청구 및 가격 책정

터미널 작업에 대한 폴링을 중단하고, 401, 403, 404 또는 재시도할 수 없는 오류 발생 시 중단하십시오. 폴링 없이 작업 결과를 받으려면 mt-… 관리 토큰을 사용하여 웹훅 관리 API를 구성하십시오.

작업 응답에는 작업 ID와 함께 기록할 수 있는 X-Task-ID, X-Task-Type 및 X-Billing-Transaction-ID 헤더도 포함되어 있습니다.

이 페이지의 내용