# Créditos

> Qué consume créditos, cuándo ocurre el cobro, cómo saber el precio antes y cómo revisar el extracto.

Los créditos son el saldo del workspace. Toda ruta que cobra dice el precio antes de cobrar, y todo débito aparece en el extracto con el id de lo que lo causó.

## Qué cobra

| Acción | Cuándo cobra | Cómo saber el precio antes |
|---|---|---|
| Clipping (`POST /clips`) | al crear el envío | `credits_cost` en `POST /clips/info` |
| Traducción de subtítulos (`translate_to`) | junto con el clipping | `credits_charged` en la respuesta de `POST /clips` |
| Transcripción (`POST /transcriptions`) | al crear, por minuto de audio, más un adicional con `speaker_labels` | `credits_charged` en la respuesta |
| Monitoreo de transmisión en vivo | por cada bloque de 10 minutos que generó clips, solo con el monitor encendido | |
| Generación de imagen, video y voz | al crear, al precio que enviaste | `GET /generations/models` |
| Persona: foto y video | al crear | `GET /personas/catalog` y `GET /personas/swap/quote` |

Leer, listar, analizar, renderizar y publicar no cobran.

## Revisa el precio antes

`POST /clips/info` no cobra nada y devuelve el costo exacto del clipping:

```json title="200 OK"
{
  "id": "7412908365112823",
  "duration": 213,
  "credits_cost": 4,
  "credits_original": 5,
  "discount_percent": 20,
  "current_balance": 120,
  "credits_unlimited": false
}
```

`credits_original` y `discount_percent` muestran el descuento aplicado, cuando lo hay.

## Saldo

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

```json title="200 OK"
{ "balance": 120, "unlimited": false, "unlimited_until": null }
```

## Saldo insuficiente

La ruta responde `402` antes de crear el job, y no se cobra nada:

```json title="402 Payment Required"
{
  "code": "INSUFFICIENT_CREDITS",
  "extra": { "credits_needed": 121, "current_balance": 40, "is_owner": true }
}
```

- `credits_needed` y `current_balance` dicen cuánto falta.
- `is_owner` dice si el dueño de la clave puede comprar créditos para este workspace.
- En generación y persona, `extra.top_up_url` es la página donde se compran créditos. Muéstrala a la persona.

## Extracto

`GET /balance/history` lista cada movimiento, del más nuevo al más antiguo:

```bash
curl "https://api.cut.pro/api/v1/balance/history?type=debit&limit=20" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "transactions": [
    {
      "id": "7412908372201188",
      "type": "debit",
      "amount": -4,
      "balance_after": 116,
      "reference_type": "usage",
      "reference_id": "7412908371004912",
      "description": null,
      "waived": false,
      "expires_at": null,
      "created_at": "2026-10-29T18:01:12.000Z"
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 1, "total_count": 1, "has_next_page": false, "has_previous_page": false, "limit": 20 }
}
```

`amount` es negativo en el débito y positivo en el crédito. `reference_id` apunta a lo que causó el movimiento (el envío, la suscripción, el reembolso). `expires_at` solo viene completo en créditos que vencen. Filtra por `type` y `reference_type`.

## Devoluciones

- **Clipping cancelado:** `DELETE` sobre un envío que aún se procesa lo cancela y devuelve los créditos.
- **Generación que falló:** vuelve sola. En una generación lista que salió mal se puede pedir el reembolso en `POST /generations/{id}/refund`, antes de descargar o publicar, y el equipo decide.
- **Transcripción repetida o sin voz:** el audio ya transcrito vuelve de la caché con `credits_charged: 0`, y el audio sin voz termina en `no_speech` sin cobro.
- **Traducción innecesaria:** si el video ya está en el idioma de `translate_to`, el adicional de la traducción se devuelve.

## Uso gratuito

Un workspace puede estar en uso gratuito. Mientras dure, los jobs corren sin consumir créditos y nunca se rechazan por saldo.

- `GET /balance` muestra `unlimited: true` y `unlimited_until` (`null` es sin fecha de término).
- `GET /workspace` trae lo mismo en `credits_unlimited` y `credits_unlimited_until`.
- `POST /clips/info` trae `credits_unlimited` junto a `credits_cost`.

El extracto sigue registrando todo: cada job aparece con el valor que habría costado y `waived: true`, y `balance_after` no cambia. Los campos de cobro real, como `credits_charged`, vienen en `0`.

> La generación con IA y las personas siempre consumen créditos, incluso en uso gratuito.