Créditos e uso

A Direct API cobra créditos do Morphic do saldo da sua organização, o mesmo saldo que o Studio usa, e toda resposta informa quantos.

• As chamadas da Direct API são cobradas pelas tarifas de API da sua organização, que podem ser diferentes do custo do mesmo trabalho no Studio. Todos os números que a API fornece já as refletem: orçamentos de plan_media, estimated_credits, o bloco billing, leituras de gerações, webhooks e /usage.
• As tarifas são definidas por organização e não são publicadas. O seu contato comercial pode compartilhar a sua tabela de tarifas da API.
• Uma mudança de tarifa vale para as gerações iniciadas depois dela; uma geração em andamento é acertada pela tarifa com que começou.
• No Studio, em Configurações > Créditos, o gasto da API aparece em uma linha própria, API, ao lado dos seus membros, e Detalhar a API por chave mostra o gasto por chave. Ele sai dos créditos da organização, mas nunca da cota de um membro, e os limites de créditos de cada chave o limitam.

Como uma geração é cobradaCopy Anchor Link

1. No início, a geração é cobrada pelo preço orçado. A resposta de início o informa em billing.credits_charged e result.estimated_credits.
2. Alguns resultados têm preço pelo que é efetivamente produzido: fala e música pela duração produzida, renderizações de linha do tempo pelo tempo de processamento. Eles trazem credits_settle_on_output_duration: true; a cobrança inicial é um piso, e o valor final é acertado quando a geração termina.
3. Uma geração que termina em failed ou cancelled é reembolsada integralmente, e billing.credits_refunded informa os créditos devolvidos. Uma geração concluída com sucesso também pode ter um reembolso parcial, por exemplo quando um resultado acertado saiu mais curto do que a cobrança inicial cobria.
4. Quando uma geração é final, billing.credits_charged é o total líquido no extrato (cobrança inicial, mais ou menos o acerto, menos credits_refunded) e credits_are_final é true. Uma geração com falha ou cancelada termina com credits_charged: 0 e credits_refunded igual ao que foi cobrado.

Enquanto uma geração está em andamento, credits_charged é igual à cobrança inicial. Leia-a de novo quando a geração for final para obter o valor acertado; um webhook só é enviado quando ela já é final.

Cobrança em cada respostaCopy Anchor Link

O bloco billing na resposta de uma chamada informa o que a chamada cobrou no momento em que respondeu; Chamar uma ferramenta o detalha por tipo de chamada. Os reembolsos acontecem depois, então aparecem na geração (GET /generations/{id} e /usage), nunca na resposta original.

• Uma ferramenta paga que responde dentro da chamada e cujo trabalho falha, como analyze_video, responde com credits_charged: 0 e credits_refunded preenchido com o reembolso.
• O cabeçalho Morphic-Credits-Charged: <integer> traz o mesmo número que billing.credits_charged, exceto em uma repetição idempotente, que não cobra nada a mais e envia 0, enquanto o corpo repete a cobrança original.

Orce antes de gastarCopy Anchor Link

POST /v1/direct/tools/plan_media valida um plano de até 20 etapas e orça as etapas que conseguir, sem iniciar nem cobrar nada.

curl -s https://mcp.morphic.com/v1/direct/tools/plan_media \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "steps": [
            { "id": "still", "tool_name": "generate_image", "arguments_json": "{\"prompt\":\"A red vintage bicycle\",\"aspect_ratio\":\"16:9\"}" },
            { "id": "clip", "tool_name": "generate_video", "arguments_json": "{\"prompt\":\"The bicycle rolls away\",\"duration_seconds\":8}", "depends_on": ["still"] }
          ]
        }
      }'

• Omita os campos de recurso cujos resultados ainda não existem e indique em depends_on a etapa de onde eles vêm.
• Cada etapa recebe a sua validation, o seu quote_status e os seus estimated_credits.
• O resultado também traz execution_order, known_estimated_credits, unquoted_step_ids e complete_estimate. Quando complete_estimate é false, a soma é um limite inferior, não um orçamento.

Chave e saldoCopy Anchor Link

GET /v1/direct/me retorna a chave que fez a chamada, seus limites e gastos, e o saldo da organização. Qualquer chave pode chamá-lo.

curl -s https://mcp.morphic.com/v1/direct/me \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "api_key": {
    "id": "01928e00-…",
    "name": "Order pipeline (prod)",
    "scopes": ["assets:read", "assets:write", "generations:write", "projects:read"],
    "expires_at": null,
    "credit_limits": {
      "total":   { "limit": 500000, "used": 182340, "remaining": 317660 },
      "monthly": { "limit": 100000, "used": 41200,  "remaining": 58800, "resets_at": "2026-11-01T00:00:00.000Z" },
      "daily":   { "limit": null,   "used": 2310,   "remaining": null,  "resets_at": "2026-10-26T00:00:00.000Z" }
    }
  },
  "organization": {
    "id": "01928d00-…",
    "plan": "enterprise",
    "remaining_credits": 1240000,
    "unlimited": false
  }
}

Extrato de usoCopy Anchor Link

GET /v1/direct/usage (escopo assets:read) retorna todos os lançamentos do extrato causados pela chave, para conciliar com os seus próprios registros.

curl -s "https://mcp.morphic.com/v1/direct/usage?from=2026-10-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "usage": [
    { "id": "0192a7b3-…", "created_at": "2026-10-25T09:14:03.500Z", "kind": "charge",     "credits": 120, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } },
    { "id": "0192a7b4-…", "created_at": "2026-10-25T09:15:41.950Z", "kind": "settlement", "credits": -24, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } }
  ],
  "totals": { "charged": 120, "settled": -24, "refunded": 0, "net": 96 },
  "next_cursor": null
}

• kind é um de charge, settlement ou refund; um credits negativo devolve créditos.
• totals cobre todo o intervalo filtrado, não apenas a página.
• Uma ferramenta que responde dentro da chamada (analyze_video, analyze_audio, filmlab_edit) não inicia nenhuma geração, então os lançamentos dela trazem generation_id: null e se distinguem por tool.

Se você tiver algum problema ou alguma dúvida, entre em contato. Teremos prazer em ajudar. Escreva para nós em support@morphic.com.