Vídeo e materiais
Obter Status do Vídeo
Obtenha o status e o resultado de uma tarefa de vídeo
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
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.
ID da tarefa.
Mesmo ID da tarefa que id.
URL de status para esta tarefa. Realize o polling em GET /v1/tasks/{id} com o id.
ID da transação de faturamento após a liquidação. É separado do ID da tarefa.
Status da tarefa: pending, processing, completed, failed.
Progresso opcional de 0 a 100. Retornado apenas quando um valor de progresso real está disponível; use status para determinar a conclusão.
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.
URL do último frame gerado, quando você solicitou com return_last_frame e o modelo suporta isso.
Resultado de vídeo único com url, duration, width e height quando disponível.
Resultados de vídeo múltiplos quando a tarefa retorna mais de uma saída.
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.
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.
Timestamp de criação.
Timestamp da última atualização.
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.502ou503 media_unavailable: o resultado ainda está sendo gravado ou a TokenLab está ocupada. Tente novamente após o atraso indicado emRetry-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
failede exiba oerrorretornado.
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 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