# Genera imagen, video y voz

> Elige un modelo, confirma el precio, genera a partir de texto o de imágenes y usa el resultado en el editor o en un post.

Una ruta genera imagen, video o voz con modelos de varios fabricantes (Veo, Kling, Seedance, Wan, Nano Banana, GPT Image, voces de ElevenLabs y otros). Creas la generación, consultas hasta que esté lista y usas el resultado.

> Generar siempre cobra, incluso en uso liberado. Muéstrale a la persona el modelo y el precio y espera el sí antes de llamar a `POST /generations`. Si falla, los créditos vuelven solos.

### Elige el modelo

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

```json title="200 OK (ejemplo 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
}
```

Los precios acompañan el costo de cada modelo y cambian sin aviso: lee esta ruta justo antes de generar.

| Campo | Para qué sirve |
|---|---|
| `modes` | `text` (solo prompt), `image` (anima una imagen), `frames` (del primer al último cuadro), `references` (toma persona, producto o estilo de las imágenes, o las edita). |
| `prices[].credits` | Por segundo de video, por imagen o por 1.000 caracteres de voz. `silent_credits` es el precio del video sin sonido. |
| `audio` | `always` tiene sonido siempre; `optional` acepta `audio: false`, en general más barato; `null` es mudo. |
| `refuses` | Lo que el modelo se niega a mostrar: `real_faces`, `minors`, `public_figures`. |
| `typical_seconds`, `success_rate` | Tiempo típico y tasa de éxito de las últimas semanas. `null` hasta que corran suficientes generaciones. |
| `presets` | El modelo recomendado por tipo y nivel (`fast`, `balanced`, `best`). Úsalo cuando la persona no elige. |
| `max_running` | Cuántas generaciones corre el workspace al mismo tiempo. |

### Envía las imágenes, si el modo lo pide

```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` | ninguna |
| `image` | una, el primer cuadro |
| `frames` | dos: primer y último cuadro |
| `references` | hasta `max_images` del modelo |

Una imagen generada por Cut.Pro no necesita subida: su `output.image_id` vale igual.

### Genera

```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": "un perro surfeando al atardecer",
    "seconds": 8,
    "aspect_ratio": "9:16",
    "credits": 96
  }'
```

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

`credits` es el total que la persona aceptó: `credits` del precio por `seconds` en un video (12 × 8 = 96). Si el precio cambió, no se cobra nada y la respuesta es `409 PRICE_CHANGED` con el nuevo total en `extra.credits`. Muestra el nuevo valor y pide el sí de nuevo.

- **Video**: `seconds` es obligatorio y debe ser uno de los `seconds` del modelo.
- **Imagen**: sin `seconds`.
- **Voz** (`kind: "speech"`, `mode: "text"`): lee el `prompt` palabra por palabra con la `voice` elegida entre las `voices` del modelo. Sin `aspect_ratio`. Sale un MP3. Cuesta `credits` por los caracteres del `prompt` divididos entre 1.000, redondeado hacia arriba.

### Sigue la generación

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

Consulta cada 10 segundos mientras `status` sea `processing`. `expected_seconds` dice cuánto suele tardar el modelo.

- `ready`: `output.url` es la vista previa (enlace de 6 horas, MP3 en una voz) y `output.thumbnail_url` la miniatura.
- `failed`: el motivo está en `error_code` y los créditos ya volvieron.

## Mejora el prompt

`POST /generations/improve` reescribe una solicitud corta de la manera que el modelo elegido entiende mejor, en el idioma de la solicitud. No genera nada. Cobra `improve_credits` y lo devuelve si falla. Muéstrale el texto nuevo a la persona antes de generar con él.

```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": "un perro surfeando al atardecer", "seconds": 8 }'
```

## Usa el resultado

| Ruta | Qué hace |
|---|---|
| `GET /generations/{id}/download` | Enlace al archivo en calidad total, válido por 6 horas. Después de descargar, ya no se pueden pedir los créditos de vuelta. |
| `POST /generations/{id}/edit` | Abre un video listo en el editor y devuelve el `edit_id`. Úsalo en [`POST /posts`](/es/publishing) o [`POST /renders`](/es/rendering). Llamar de nuevo devuelve el mismo. |
| `GET /generations` | Lista las generaciones, de la más nueva a la más antigua. Filtra con `kind`. |
| `DELETE /generations/{id}` | La saca de la lista y elimina el archivo de la biblioteca. No vale para una en `processing`. |

## Evalúa o pide los créditos de vuelta

Evaluar es gratis y ayuda a elegir 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` es `up`, `down` o `null` (limpia). Con `down`, `reason` es uno de `prompt_ignored`, `defects`, `bad_motion`, `not_realistic`, `speech_wrong` (palabra, nombre o número dicho mal) u `other`. Un `down` cancela los posts de ese resultado que aún están programados.

Si el resultado no sirve, pide el reembolso con el mismo `reason` y una `note` corta:

```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": "Las manos salen deformadas en todos los planos." }'
```

El equipo lo analiza. `refund_status` pasa de `requested` a `approved` o `denied`.

> El reembolso vale una vez por generación, solo en `ready`, y nunca después de descargar o publicar: `409 REFUND_AFTER_DOWNLOAD` y `409 REFUND_AFTER_POST`.

## Errores

| Code | Cuándo |
|---|---|
| `INSUFFICIENT_CREDITS` | Saldo insuficiente. `extra.top_up_url` lleva a la recarga; `extra.is_owner` dice si quien llamó puede recargar. |
| `PRICE_CHANGED` | El precio cambió. El nuevo total está en `extra.credits`. |
| `TOO_MANY_RUNNING` | El workspace ya tiene `max_running` generaciones corriendo. Espera a que una termine. |
| `MODEL_UNAVAILABLE`, `MODE_UNSUPPORTED`, `RESOLUTION_INVALID`, `SECONDS_INVALID`, `RATIO_INVALID`, `IMAGES_INVALID`, `VOICE_INVALID` | La solicitud no coincide con lo que acepta el modelo. Revisa en `GET /generations/models`. |
| `IMAGE_NOT_FOUND` | Un `image_ids` no es de este workspace. |

Cuando la generación termina en `failed`, `error_code` dice por qué: `SAFETY_BLOCKED`, `COPYRIGHT_BLOCKED` y `REAL_FACES_BLOCKED` son rechazos del modelo por el contenido (cambia la solicitud o el modelo); `TIMEOUT` y `MEDIA_FAILED` valen un nuevo intento.