---
title: "API do Hypio"
description: "Gere vídeo, imagem e voz pelo seu código. Uma chave, um endpoint de geração, e cada pedido vira uma geração que você consulta ou recebe por webhook."
source_url: "https://staging-hypio.doti.gg/docs"
updated: "2026-11-11"
---

# API do Hypio

Gere vídeo, imagem e voz pelo seu código. Uma chave, um endpoint de geração, e cada pedido vira uma geração que você consulta ou recebe por webhook.

## Resumo

|   |   |
| --- | --- |
| URL base | `https://staging-hypio.doti.gg/api/v1` |
| Autenticação | `Authorization: Bearer <chave>` |
| Chaves | [Configurações → Chaves de API](https://staging-hypio.doti.gg/configuracoes/api-keys) |
| Cobrança | Saldo pré-pago em reais. Valores da API em centavos. Veja [Saldo e cobrança](https://staging-hypio.doti.gg/docs/cobranca). |
| Corpo | JSON na ida e na volta. Sucesso devolve o objeto; erro devolve `error`. |

## Faça uma chamada

Este pedido gera uma imagem com `seedream-5.0-flash` por R$ 0,17. A resposta chega na hora com a geração na fila; o arquivo fica pronto em segundos.

cURL:

```bash
curl -X POST https://staging-hypio.doti.gg/api/v1/generations \
  -H "Authorization: Bearer $HYPIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "kind": "image",
  "model": "seedream-5.0-flash",
  "prompt": "Uma xícara de café numa mesa de madeira, luz suave da manhã",
  "ratio": "1:1",
  "resolution": "1K"
}'

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

JavaScript:

```javascript
const API = "https://staging-hypio.doti.gg/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.HYPIO_API_KEY}`,
  "Content-Type": "application/json",
};

let generation = await fetch(`${API}/generations`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({
    "kind": "image",
    "model": "seedream-5.0-flash",
    "prompt": "Uma xícara de café numa mesa de madeira, luz suave da manhã",
    "ratio": "1:1",
    "resolution": "1K"
  }),
}).then((res) => res.json());

while (generation.status === "queued" || generation.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  generation = await fetch(`${API}/generations/${generation.id}`, { headers })
    .then((res) => res.json());
}

console.log(generation.status, generation.outputs);
```

Python:

```python
import os, time, uuid
import requests

API = "https://staging-hypio.doti.gg/api/v1"
headers = {"Authorization": f"Bearer {os.environ['HYPIO_API_KEY']}"}

generation = requests.post(
    f"{API}/generations",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={
      "kind": "image",
      "model": "seedream-5.0-flash",
      "prompt": "Uma xícara de café numa mesa de madeira, luz suave da manhã",
      "ratio": "1:1",
      "resolution": "1K"
    },
).json()

while generation["status"] in ("queued", "running"):
    time.sleep(5)
    generation = requests.get(f"{API}/generations/{generation['id']}", headers=headers).json()

print(generation["status"], generation["outputs"])
```

202 Accepted:

```json
{
  "id": "0b7c1e5a-4d2f-4c8e-9a51-6f3d2b8e7c10",
  "object": "generation",
  "kind": "image",
  "model": "seedream-5.0-flash",
  "status": "queued",
  "prompt": "Uma xícara de café numa mesa de madeira, luz suave da manhã",
  "ratio": "1:1",
  "resolution": "1K",
  "durationSeconds": null,
  "audio": null,
  "count": 1,
  "priceCredits": 17,
  "error": null,
  "outputs": [],
  "createdAt": "2026-11-11T14:02:11.000Z",
  "startedAt": null,
  "finishedAt": null
}
```

## Como uma geração funciona

1. **Envie.** `POST /v1/generations` com `kind`, `model` e o prompt. A API confere o corpo, reserva o preço e responde `202` com o `id`.
2. **Espere.** Consulte `GET /v1/generations/{id}` até o `status` sair de `queued` e `running`, ou receba o evento por [webhook](https://staging-hypio.doti.gg/docs/webhooks).
3. **Baixe.** Cada item de `outputs` tem uma `url` da própria API. Geração que falha devolve a reserva.

## Próximos passos

- [Início rápido](https://staging-hypio.doti.gg/docs/inicio-rapido): Uma chave, uma imagem, o arquivo em quatro passos.
- [Autenticação](https://staging-hypio.doti.gg/docs/autenticacao): Criar, enviar e restringir chaves.
- [Modelos](https://staging-hypio.doti.gg/docs/modelos): Cada `model`, o que ele gera e quanto custa.
- [Vídeo](https://staging-hypio.doti.gg/docs/video): Texto para vídeo, com ou sem som.
- [Imagem](https://staging-hypio.doti.gg/docs/imagem): Texto para imagem, de 1 a 4 por pedido.
- [Áudio](https://staging-hypio.doti.gg/docs/audio): Texto para voz, com a voz escolhida.
- [Gerações](https://staging-hypio.doti.gg/docs/geracoes): Estados, consulta, idempotência e download.
- [Webhooks](https://staging-hypio.doti.gg/docs/webhooks): Eventos assinados quando a geração termina.