Generación asíncrona de imágenes

Qué es la generación asíncrona

Para solicitudes de generación de imágenes que consumen tiempo, la plataforma soporta el modo asíncrono: al enviar la solicitud se devuelve inmediatamente un ID de tarea. El cliente consulta el resultado final mediante polling, sin mantener una conexión larga.

El modo asíncrono es ideal para escenarios con tiempos de generación prolongados y evita interrupciones por timeout. También permite enviar varias tareas en lote.

Flujo de uso

Tres pasos: enviar → consultar → descargar.

1. Enviar la tarea

Envía un POST a https://api.tvtapi.com/v1/images/async con tu API Key (Bearer) y los 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 descriptivo"}'

La respuesta incluye un task_id, tu credencial para consultar y descargar.

2. Consultar el estado

Consulta el estado con task_id:

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

Estados: queued (en cola), in_progress (generando), succeeded (éxito), failed (fallo). Consulta cada pocos segundos hasta que el estado sea succeeded o failed.

3. Descargar la imagen

Tras el éxito, descarga desde:

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

Este endpoint devuelve una redirección 302 a la URL real de almacenamiento. Cada imagen tiene un límite de descargas; la tarea expira tras el timeout.

También en la web

Si no quieres escribir código, usa el banco de trabajo de imágenes en /es-es/user/image-studio. Incluye un conmutador asíncrono que, al activarse, consulta automáticamente y muestra los resultados.

Notas

  • La función asíncrona requiere que un administrador la habilite y que la cuenta de usuario tenga el permiso correspondiente
  • Las tareas tienen un período de validez; las expiradas no se pueden descargar
  • Si una tarea permanece en in_progress demasiado tiempo, el sistema la marca automáticamente como failed