Créditos

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é cobraCopy Anchor Link

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

Revisa el precio antesCopy Anchor Link

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

{
  "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.

SaldoCopy Anchor Link

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

{ "balance": 120, "unlimited": false, "unlimited_until": null }

Saldo insuficienteCopy Anchor Link

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

{
  "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.

ExtractoCopy Anchor Link

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

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

{
  "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.

DevolucionesCopy Anchor Link

• 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 gratuitoCopy Anchor Link

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.