Tarefas assíncronas
Obter Status da Tarefa
Recupere o status e o resultado de qualquer tarefa assíncrona: imagens, vídeo, música, 3D, Worlds e transcrição de áudio assíncrona
Visão Geral
Use GET /v1/tasks/{id} para verificar qualquer tarefa assíncrona. Ele atende a tarefas de imagem, vídeo, música, 3D, Worlds e transcrição de áudio assíncrona. Passe o id ou task_id da resposta de criação.
Os campos de resultado de World, como world_id e world_marble_url, estão documentados em Obter Status de World. Para uma tarefa de World, o X-Task-Type é 3d.
Para a maioria das tarefas, o poll_url na resposta de criação é este mesmo caminho. Uma resposta de criação de Worlds retorna um poll_url em /v1/worlds/generations/{id}; faça o polling de /v1/tasks/{id} com o id da tarefa para Worlds também.
Caminhos de status por modalidade, como /v1/images/{id}, /v1/videos/generations/{id}, /v1/music/generations/{id} e /v1/3d/generations/{id}, são endpoints de compatibilidade. Eles permanecem suportados para integrações existentes.
Uma leitura de status retorna HTTP 200 para uma tarefa que falhou. Leia o status, não o código HTTP, para ver o resultado. Os campos de resultado dependem do tipo de tarefa; veja Obter Status de Imagem, Obter Status de Vídeo, Obter Status de Música e Obter Status de 3D. Os links de resultado são URLs de mídia da TokenLab que permanecem válidos por 30 dias; veja Retenção de dados.
Parâmetros de Caminho
O id ou task_id retornado pela requisição de criação.
Resposta
Campos que descrevem resultados, erros, timestamps e o modelo são retornados quando disponíveis para a tarefa.
Identificador canônico da tarefa assíncrona.
Alias do identificador da tarefa assíncrona.
URL de status para esta tarefa. Faça o polling de GET /v1/tasks/{id} com o id.
ID da transação de faturamento, quando registrado para a tarefa. O cabeçalho X-Billing-Transaction-ID carrega o mesmo valor. É um identificador de faturamento, não um identificador de tarefa.
Status da tarefa: pending, processing, completed, failed ou timeout. Pare o polling em completed, failed ou timeout. Tarefas canceladas são representadas como failed com cancelled: true.
true quando uma tarefa assíncrona na fila foi cancelada antes da execução.
Marcador de cancelamento. Apresentado como cancelled quando o cancelamento é bem-sucedido.
Para tarefas de imagem concluídas, os resultados das imagens geradas são retornados aqui. Tarefas de imagem retornam URLs em data[].url.
Valor de progresso opcional. Retornado apenas quando um valor de progresso real está disponível; use status para determinar a conclusão.
URL do ativo de resultado quando a tarefa é concluída e produz um vídeo.
Payload de vídeo único com url, duration, width e height quando disponível.
Payloads de vídeo múltiplos quando mais de uma saída está disponível.
Por que a tarefa falhou: uma string ou um objeto com message e, quando conhecido, type, code, param e retryable.
Detalhes da falha quando a tarefa falhou: status, message, type, code, retryable e param quando um campo da requisição está com erro.
Status de salvamento dos links de resultado: days e items[] com url, kind, status e expires_at. Pode estar ausente; os links continuam funcionando.
Timestamp de criação quando disponível.
Timestamp da última atualização quando disponível.
Modelo usado pela tarefa quando disponível.
Cabeçalhos de Resposta
Respostas de status bem-sucedidas incluem estes cabeçalhos:
| Cabeçalho | Descrição |
|---|---|
X-Task-ID | ID público da tarefa |
X-Task-Type | Família da tarefa, como image, video, music, 3d ou audio |
Cache-Control | no-store. Não faça cache de respostas de status |
X-Billing-Transaction-ID | ID da transação de faturamento, quando registrado |
X-Task-Cost | Custo liquidado da tarefa, quando a tarefa foi liquidada |
Comportamento de Erro
| HTTP | Código | Significado |
|---|---|---|
400 | missing_task_id, invalid_task_id | O ID da tarefa está faltando ou não é um ID de tarefa válido |
403 | task_not_owned | A tarefa não pertence ao workspace desta API key. Pare de fazer o polling |
404 | async_task_not_found | A tarefa expirou ou não está disponível |
503 | async_task_owner_unavailable | A tarefa não pode ser lida no momento. Tente novamente |
{
"error": {
"message": "Task not found or no longer available.",
"type": "invalid_request_error",
"code": "async_task_not_found"
}
}Requisição
curl "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
-H "Authorization: Bearer sk-your-api-key"{ "id": "string", "status": "pending", "progress": 0, "created": 0, "updated": 0, "model": "string", "video": { "url": "string", "duration": 0, "width": 0, "height": 0 }, "error": "string", "error_details": { "projection_version": 0, "status": 400, "message": "string", "type": "string", "code": "string", "param": "string", "retryable": true, "upstream": { "source": "string", "code": "string", "message": "string", "param": "string" } }, "task_id": "string", "poll_url": "string", "cancelled": true, "cancellation_status": "cancelled", "billing_transaction_id": "string", "video_url": "string", "last_frame_url": "string", "videos": [ {} ], "data": [ {} ], "audio_url": "string", "title": "string", "lyrics": "string", "model_url": "string", "glb_url": "string", "fbx_url": "string", "media_retention": { "days": 0, "items": [ { "url": "http://example.com", "kind": "image", "content_type": "string", "status": "saving", "expires_at": "2019-08-24T14:15:22Z" } ] }}Autorização
BearerAuth Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Parâmetros de caminho
O ID da tarefa assíncrona retornado por id / task_id, ou incorporado na poll_url
Resposta
application/json
application/json
application/json
application/json
application/json
application/json
application/json