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_progresspor muito tempo, o sistema a marca automaticamente comofailed