Geração assíncrona de imagens

O que é geração assíncrona

Para requisições de geração de imagens demoradas, a plataforma suporta o modo assíncrono: após o envio, um ID de tarefa é retornado imediatamente. O cliente obtém o resultado final por polling, sem manter uma conexão longa.

O modo assíncrono é ideal para cenários com tempos de geração longos e evita interrupções por timeout. Também permite enviar várias tarefas em lote.

Fluxo de uso

Três etapas: enviar → consultar → baixar.

1. Enviar a tarefa

Envie um POST para https://api.tvtapi.com/v1/images/async com sua API Key (Bearer) e parâmetros:

curl -X POST https://api.tvtapi.com/v1/images/async \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"model-name","prompt":"texto descritivo"}'

A resposta inclui um task_id — sua credencial para consulta e download.

2. Consultar o status

Consulte o status com task_id:

curl https://api.tvtapi.com/v1/images/async/{task_id} \
  -H "Authorization: Bearer sk-xxxxxxxx"

Estados: queued (na fila), in_progress (gerando), succeeded (sucesso), failed (falha). Consulte a cada poucos segundos até o estado ser succeeded ou failed.

3. Baixar a imagem

Após o sucesso, baixe via:

curl -L https://api.tvtapi.com/v1/images/async/{task_id}/content \
  -H "Authorization: Bearer sk-xxxxxxxx"

Este endpoint retorna um redirecionamento 302 para a URL real de armazenamento. Cada imagem tem um limite de downloads; a tarefa expira após o timeout.

Também na web

Se você não quer escrever código, use a bancada de imagens em /pt-br/user/image-studio. Ela tem um alternador assíncrono integrado que, ao ser ativado, consulta automaticamente e exibe os resultados.

Notas

  • A funcionalidade assíncrona exige que um administrador a ative e que a conta do usuário tenha a permissão correspondente
  • As tarefas têm um período de validade; as expiradas não podem ser baixadas
  • Se uma tarefa permanecer em in_progress por muito tempo, o sistema a marca automaticamente como failed