---
title: "Gerações e consulta"
description: "Os estados de uma geração, como consultar, repetir com segurança e baixar o resultado."
source_url: "https://hypio.doti.gg/docs/geracoes"
updated: "2026-11-11"
---

# Gerações e consulta

Os estados de uma geração, como consultar, repetir com segurança e baixar o resultado.

## Estados

| `status` | Significa |
| --- | --- |
| `queued` | Aceita e com o preço reservado. Esperando o modelo. |
| `running` | O modelo está gerando. |
| `succeeded` | Pronta. `outputs` tem os arquivos e a reserva vira cobrança. |
| `failed` | Não gerou. `error` diz o motivo e a reserva volta para o saldo. |

Uma geração que passa de 14 minutos sem terminar vira `failed`. Não existe cancelamento.

## Consultar

```bash
curl https://hypio.doti.gg/api/v1/generations/<id> \
  -H "Authorization: Bearer $HYPIO_API_KEY"
```

Consulte a cada 5 segundos. Imagem e áudio terminam em segundos; vídeo leva minutos. Para não consultar, use [webhooks](https://hypio.doti.gg/docs/webhooks).

## Listar

`GET /v1/generations` devolve as mais recentes primeiro. Filtros: `limit` (1 a 50, padrão 20), `kind` e `cursor`. Passe o `nextCursor` da resposta para a próxima página; `null` é o fim.

## Repetir com segurança

Mande `Idempotency-Key` no `POST`: até 64 caracteres entre letras, números e `. _ : -`. A mesma chave devolve a geração já criada com status `200` e `Idempotent-Replayed: true`, sem cobrar de novo. O corpo do replay não é comparado.

> Sem `Idempotency-Key`, cada `POST` cria e cobra uma geração nova, inclusive numa nova tentativa depois de timeout.

## Baixar

`GET /v1/generations/{id}/outputs/{index}` devolve o arquivo e pede a chave. Por isso a `url` não funciona direto num `<img>` do navegador: baixe no servidor e sirva do seu storage.

## Motivos de falha

O campo `error` traz uma destas mensagens. O texto do provedor nunca sai da API.

| Motivo | `error` |
| --- | --- |
| `content_blocked` | O modelo não aceitou este conteúdo. Mude o texto ou a imagem e tente de novo. |
| `real_person` | O modelo não aceita foto com pessoa real. Use uma imagem sem pessoas e descreva quem aparece no texto. |
| `invalid_input` | O modelo não conseguiu usar o texto ou a imagem enviada. Ajuste e tente de novo. |
| `unavailable` | A geração está indisponível agora. Tente de novo em alguns minutos. |
| `failed` | Não conseguimos gerar desta vez. Tente de novo. |