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

GET
/v1/tasks/{id}

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

idstringpathobrigatório

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.

idstring

Identificador canônico da tarefa assíncrona.

task_idstring

Alias do identificador da tarefa assíncrona.

poll_urlstring

URL de status para esta tarefa. Faça o polling de GET /v1/tasks/{id} com o id.

billing_transaction_idstring

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.

statusstring

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.

cancelledboolean

true quando uma tarefa assíncrona na fila foi cancelada antes da execução.

cancellation_statusstring

Marcador de cancelamento. Apresentado como cancelled quando o cancelamento é bem-sucedido.

dataarray

Para tarefas de imagem concluídas, os resultados das imagens geradas são retornados aqui. Tarefas de imagem retornam URLs em data[].url.

progressnumber

Valor de progresso opcional. Retornado apenas quando um valor de progresso real está disponível; use status para determinar a conclusão.

video_urlstring

URL do ativo de resultado quando a tarefa é concluída e produz um vídeo.

videoobject

Payload de vídeo único com url, duration, width e height quando disponível.

videosarray

Payloads de vídeo múltiplos quando mais de uma saída está disponível.

errorstring | object

Por que a tarefa falhou: uma string ou um objeto com message e, quando conhecido, type, code, param e retryable.

error_detailsobject

Detalhes da falha quando a tarefa falhou: status, message, type, code, retryable e param quando um campo da requisição está com erro.

media_retentionobject

Status de salvamento dos links de resultado: days e items[] com url, kind, status e expires_at. Pode estar ausente; os links continuam funcionando.

createdinteger

Timestamp de criação quando disponível.

updatedinteger

Timestamp da última atualização quando disponível.

modelstring

Modelo usado pela tarefa quando disponível.

Cabeçalhos de Resposta

Respostas de status bem-sucedidas incluem estes cabeçalhos:

CabeçalhoDescrição
X-Task-IDID público da tarefa
X-Task-TypeFamília da tarefa, como image, video, music, 3d ou audio
Cache-Controlno-store. Não faça cache de respostas de status
X-Billing-Transaction-IDID da transação de faturamento, quando registrado
X-Task-CostCusto liquidado da tarefa, quando a tarefa foi liquidada

Comportamento de Erro

HTTPCódigoSignificado
400missing_task_id, invalid_task_idO ID da tarefa está faltando ou não é um ID de tarefa válido
403task_not_ownedA tarefa não pertence ao workspace desta API key. Pare de fazer o polling
404async_task_not_foundA tarefa expirou ou não está disponível
503async_task_owner_unavailableA 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"
  }
}

Exemplos

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
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Parâmetros de caminho

id*string

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