# Gere imagem, vídeo e voz

> Escolha um modelo, combine o preço, gere a partir de texto ou de imagens e use o resultado no editor ou num post.

Uma rota gera imagem, vídeo ou voz com os modelos de vários fabricantes (Veo, Kling, Seedance, Wan, Nano Banana, GPT Image, vozes da ElevenLabs e outros). Você cria a geração, consulta até ficar pronta e usa o resultado.

> Gerar sempre cobra, mesmo em uso liberado. Mostre à pessoa o modelo e o preço e espere o sim antes de chamar `POST /generations`. Se falhar, os créditos voltam sozinhos.

### Escolha o modelo

```bash
curl https://api.cut.pro/api/v1/generations/models \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK (exemplo resumido)"
{
  "models": [
    {
      "id": "google/veo-3.1-lite",
      "name": "Veo 3.1 Lite",
      "kind": "video",
      "modes": ["text", "image", "frames"],
      "resolutions": ["720p", "1080p"],
      "seconds": [4, 6, 8],
      "aspect_ratios": ["16:9", "9:16"],
      "audio": "always",
      "max_images": 2,
      "typical_seconds": 74,
      "success_rate": 0.97,
      "prices": [{ "mode": "text", "resolution": "720p", "credits": 12, "silent_credits": null }]
    }
  ],
  "presets": { "video": [{ "id": "balanced", "model": "google/veo-3.1-lite", "resolution": "720p" }] },
  "prompt_max": 4000,
  "max_running": 4,
  "improve_credits": 1
}
```

Os preços acompanham o custo de cada modelo e mudam sem aviso: leia esta rota logo antes de gerar.

| Campo | Para que serve |
|---|---|
| `modes` | `text` (só prompt), `image` (anima uma imagem), `frames` (do primeiro ao último quadro), `references` (pega pessoa, produto ou estilo das imagens, ou as edita). |
| `prices[].credits` | Por segundo de vídeo, por imagem ou por 1.000 caracteres de voz. `silent_credits` é o preço do vídeo sem som. |
| `audio` | `always` tem som sempre; `optional` aceita `audio: false`, em geral mais barato; `null` é mudo. |
| `refuses` | O que o modelo se recusa a mostrar: `real_faces`, `minors`, `public_figures`. |
| `typical_seconds`, `success_rate` | Tempo típico e taxa de sucesso das últimas semanas. `null` até rodarem gerações suficientes. |
| `presets` | O modelo recomendado por tipo e nível (`fast`, `balanced`, `best`). Use quando a pessoa não escolhe. |
| `max_running` | Quantas gerações o workspace roda ao mesmo tempo. |

### Envie as imagens, se o modo pedir

```bash
curl -X POST https://api.cut.pro/api/v1/generations/images \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -F "image=@produto.jpg"
```

```json title="201 Created"
{ "id": "7412960011002233" }
```

| `mode` | `image_ids` |
|---|---|
| `text` | nenhuma |
| `image` | uma, o primeiro quadro |
| `frames` | duas: primeiro e último quadro |
| `references` | até `max_images` do modelo |

Uma imagem gerada pela Cut.Pro não precisa de upload: o `output.image_id` dela vale igual.

### Gere

```bash
curl -X POST https://api.cut.pro/api/v1/generations \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "video",
    "model": "google/veo-3.1-lite",
    "mode": "text",
    "resolution": "720p",
    "prompt": "um cachorro surfando ao pôr do sol",
    "seconds": 8,
    "aspect_ratio": "9:16",
    "credits": 96
  }'
```

```json title="201 Created"
{ "id": "7412960099887766", "status": "processing", "credits_charged": 96 }
```

`credits` é o total que a pessoa aceitou: `credits` do preço vezes `seconds` num vídeo (12 × 8 = 96). Se o preço mudou, nada é cobrado e a resposta é `409 PRICE_CHANGED` com o novo total em `extra.credits`. Mostre o novo valor e peça o sim de novo.

- **Vídeo**: `seconds` é obrigatório e tem de ser um dos `seconds` do modelo.
- **Imagem**: sem `seconds`.
- **Voz** (`kind: "speech"`, `mode: "text"`): lê o `prompt` palavra por palavra na `voice` escolhida entre as `voices` do modelo. Sem `aspect_ratio`. Sai um MP3. Custa `credits` vezes os caracteres do `prompt` dividido por 1.000, arredondado para cima.

### Acompanhe

```bash
curl https://api.cut.pro/api/v1/generations/7412960099887766 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

Consulte a cada 10 segundos enquanto `status` for `processing`. `expected_seconds` diz quanto o modelo costuma levar.

- `ready`: `output.url` é a prévia (link de 6 horas, MP3 numa voz) e `output.thumbnail_url` a miniatura.
- `failed`: o motivo está em `error_code` e os créditos já voltaram.

## Melhore o prompt

`POST /generations/improve` reescreve um pedido curto do jeito que o modelo escolhido entende melhor, no idioma do pedido. Não gera nada. Cobra `improve_credits` e devolve se falhar. Mostre o texto novo à pessoa antes de gerar com ele.

```bash
curl -X POST https://api.cut.pro/api/v1/generations/improve \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "google/veo-3.1-lite", "mode": "text", "prompt": "um cachorro surfando ao pôr do sol", "seconds": 8 }'
```

## Use o resultado

| Rota | O que faz |
|---|---|
| `GET /generations/{id}/download` | Link para o arquivo em qualidade total, válido por 6 horas. Depois de baixar, não dá mais para pedir os créditos de volta. |
| `POST /generations/{id}/edit` | Abre um vídeo pronto no editor e devolve o `edit_id`. Use em [`POST /posts`](/publishing) ou [`POST /renders`](/rendering). Chamar de novo devolve o mesmo. |
| `GET /generations` | Lista as gerações, da mais nova à mais antiga. Filtre com `kind`. |
| `DELETE /generations/{id}` | Tira da lista e apaga o arquivo da biblioteca. Não vale para uma em `processing`. |

## Avalie ou peça os créditos de volta

Avaliar é grátis e ajuda a escolher modelos:

```bash
curl -X POST https://api.cut.pro/api/v1/generations/7412960099887766/feedback \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vote": "down", "reason": "bad_motion" }'
```

`vote` é `up`, `down` ou `null` (limpa). Com `down`, `reason` é um de `prompt_ignored`, `defects`, `bad_motion`, `not_realistic`, `speech_wrong` (palavra, nome ou número dito errado) ou `other`. Um `down` cancela os posts desse resultado que ainda estão agendados.

Se o resultado não serve, peça o reembolso com o mesmo `reason` e uma `note` curta:

```bash
curl -X POST https://api.cut.pro/api/v1/generations/7412960099887766/refund \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "defects", "note": "As mãos saem deformadas em todos os planos." }'
```

A equipe analisa. `refund_status` vai de `requested` para `approved` ou `denied`.

> O reembolso vale uma vez por geração, só em `ready`, e nunca depois de baixar ou postar: `409 REFUND_AFTER_DOWNLOAD` e `409 REFUND_AFTER_POST`.

## Erros

| Code | Quando |
|---|---|
| `INSUFFICIENT_CREDITS` | Saldo insuficiente. `extra.top_up_url` leva à recarga; `extra.is_owner` diz se quem chamou pode recarregar. |
| `PRICE_CHANGED` | O preço mudou. O novo total está em `extra.credits`. |
| `TOO_MANY_RUNNING` | O workspace já tem `max_running` gerações rodando. Espere uma terminar. |
| `MODEL_UNAVAILABLE`, `MODE_UNSUPPORTED`, `RESOLUTION_INVALID`, `SECONDS_INVALID`, `RATIO_INVALID`, `IMAGES_INVALID`, `VOICE_INVALID` | O pedido não bate com o que o modelo aceita. Confira em `GET /generations/models`. |
| `IMAGE_NOT_FOUND` | Um `image_ids` não é deste workspace. |

Quando a geração termina em `failed`, `error_code` diz por quê: `SAFETY_BLOCKED`, `COPYRIGHT_BLOCKED` e `REAL_FACES_BLOCKED` são recusas do modelo pelo conteúdo (mude o pedido ou o modelo); `TIMEOUT` e `MEDIA_FAILED` valem nova tentativa.