Créditos

Créditos são o saldo do workspace. Toda rota que cobra diz o preço antes de cobrar, e todo débito aparece no extrato com o id do que o causou.

O que cobraCopy Anchor Link

Ler, listar, analisar, renderizar e publicar não cobram.

Confira o preço antesCopy Anchor Link

POST /clips/info não cobra nada e devolve o custo exato da clipagem:

{
  "id": "7412908365112823",
  "duration": 213,
  "credits_cost": 4,
  "credits_original": 5,
  "discount_percent": 20,
  "current_balance": 120,
  "credits_unlimited": false
}

credits_original e discount_percent mostram o desconto aplicado, quando houver.

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

A rota responde 402 antes de criar o job, e nada é cobrado:

{
  "code": "INSUFFICIENT_CREDITS",
  "extra": { "credits_needed": 121, "current_balance": 40, "is_owner": true }
}

• credits_needed e current_balance dizem quanto falta.
• is_owner diz se o dono da chave pode comprar créditos para este workspace.
• Em geração e persona, extra.top_up_url é a página onde se compram créditos. Mostre para a pessoa.

ExtratoCopy Anchor Link

GET /balance/history lista cada movimento, do mais novo para o mais antigo:

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 é negativo no débito e positivo no crédito. reference_id aponta para o que causou o movimento (a submissão, a assinatura, o reembolso). expires_at só vem preenchido em créditos que vencem. Filtre por type e reference_type.

DevoluçõesCopy Anchor Link

• Clipagem cancelada: DELETE numa submissão ainda em processamento cancela e devolve os créditos.
• Geração que falhou: volta sozinha. Geração pronta que saiu errada pode ter o reembolso pedido em POST /generations/{id}/refund, antes de baixar ou postar, e a equipe decide.
• Transcrição repetida ou sem fala: áudio já transcrito volta do cache com credits_charged: 0, e áudio sem fala termina em no_speech sem cobrança.
• Tradução desnecessária: se o vídeo já está no idioma de translate_to, o adicional da tradução volta.

Uso gratuitoCopy Anchor Link

Um workspace pode estar em uso gratuito. Enquanto durar, os jobs rodam sem consumir créditos e nunca são recusados por saldo.

• GET /balance mostra unlimited: true e unlimited_until (null é sem data para acabar).
• GET /workspace traz o mesmo em credits_unlimited e credits_unlimited_until.
• POST /clips/info traz credits_unlimited junto do credits_cost.

O extrato continua registrando tudo: cada job aparece com o valor que teria custado e waived: true, e balance_after não muda. Campos de cobrança real, como credits_charged, vêm 0.