Vídeo e materiais

Obter Status do Vídeo

Obtenha o status e o resultado de uma tarefa de vídeo

GET
/v1/tasks/{id}

GET /v1/videos/generations/{id} é um endpoint de compatibilidade. Ele permanece suportado para integrações existentes e retorna o resultado no mesmo formato que GET /v1/tasks/{id}. Novas integrações devem realizar o polling em GET /v1/tasks/{id}; veja Obter Status da Tarefa.

Parâmetros de Caminho

idstringpathobrigatório

O ID da tarefa retornado pela requisição de criação de vídeo. id e task_id identificam a mesma tarefa.

Uma leitura de status retorna HTTP 200 mesmo quando a tarefa falha; verifique o campo status. Uma tarefa expirada ou indisponível retorna 404 async_task_not_found. Uma tarefa que não pertence ao seu workspace retorna 403 task_not_owned. 503 async_task_owner_unavailable é temporário: tente novamente a requisição.

Resposta

Campos que descrevem resultados, erros, timestamps e o modelo são retornados quando disponíveis para a tarefa.

idstring

ID da tarefa.

task_idstring

Mesmo ID da tarefa que id.

poll_urlstring

URL de status para esta tarefa. Realize o polling em GET /v1/tasks/{id} com o id.

billing_transaction_idstring

ID da transação de faturamento após a liquidação. É separado do ID da tarefa.

statusstring

Status da tarefa: pending, processing, completed, failed.

progressinteger

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

video_urlstring

URL do vídeo gerado (quando concluído). É uma URL de resultado de mídia da TokenLab que permanece válida por 30 dias; veja Baixar o resultado. Tarefas falhas ou inacabadas não retornam URL de vídeo.

last_frame_urlstring

URL do último frame gerado, quando você solicitou com return_last_frame e o modelo suporta isso.

videoobject

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

videosarray

Resultados de vídeo múltiplos quando a tarefa retorna mais de uma saída.

errorstring | object

Por que a tarefa falhou (apenas quando status é failed): uma string ou um objeto com message e, quando conhecido, type, code, param e retryable. Uma tarefa falha também pode conter error_details; veja Jobs assíncronos e polling.

media_retentionobject

Status de salvamento do vídeo: days e items, cada um com url, kind, status e expires_at. Pode estar ausente quando o status não é conhecido a tempo; a URL continua funcionando.

createdinteger

Timestamp de criação.

updatedinteger

Timestamp da última atualização.

modelstring

Modelo utilizado para a tarefa.

Requisição

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

Resposta

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

Baixar o Resultado

video_url tem o formato https://api.tokenlab.sh/v1/media-results/{id}.mp4?token=…. O token na URL é a credencial, portanto, nenhum cabeçalho Authorization é necessário. Compartilhe a URL apenas com pessoas que podem visualizar o vídeo. A URL redireciona para o arquivo, então siga os redirecionamentos ao baixar (curl -L).

  • Ela permanece válida por 30 dias a partir do momento em que o resultado é registrado pela primeira vez. Baixe o arquivo se precisar dele por mais tempo; veja Retenção de dados.
  • 404 media_not_found: o token ou a extensão do arquivo não corresponde ao resultado. Use a URL exata que você recebeu.
  • 410 media_expired: o período de 30 dias terminou.
  • 502 ou 503 media_unavailable: o resultado ainda está sendo gravado ou a TokenLab está ocupada. Tente novamente após o atraso indicado em Retry-After.
  • Adicione metadata=true à URL para ler o status de salvamento em vez do arquivo.

Alguns resultados são entregues como https://api.tokenlab.sh/v1/videos/generations/{id}/content. Essa URL requer o mesmo cabeçalho Authorization: Bearer que você usa para o polling, e apenas o workspace que possui a tarefa pode abri-la.

Intervalo de Verificação

  • Verifique a cada 5–10 segundos.
  • Aumente o intervalo para tarefas de longa duração.
  • Defina um tempo máximo de espera para sua aplicação.
  • Pare quando o status for failed e exiba o error retornado.
import requests
import time

def wait_for_video(task_id, max_wait=600, interval=5):
    """Aguardar vídeo com timeout."""
    start = time.time()

    while time.time() - start < max_wait:
        response = requests.get(
            f"https://api.tokenlab.sh/v1/tasks/{task_id}",
            headers={"Authorization": "Bearer sk-your-api-key"}
        )
        response.raise_for_status()
        data = response.json()

        if data["status"] == "completed":
            return data["video_url"]
        elif data["status"] == "failed":
            raise Exception(data.get("error", "Falha na geração do vídeo"))

        time.sleep(interval)

    raise TimeoutError("Tempo limite de geração de vídeo excedido")

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