Generation credits

Generation uses credits. Read your balance before submitting work and review a plan before generating a whole character or canvas.

What generation costs

A five-second Standard animation from an existing image costs 10 credits, or 11 credits with a new source image. Premium costs 30 credits, or 31 credits with a new source image. Pass animation_model explicitly to select these rates; omission preserves legacy pricing. Reusing a reversed clip is free.

Background removal, video format conversion, and animation resizing add no generation credits. Preview images are paid even though their URLs are temporary. Reading metadata, analyzing an image or website, and reviewing a generation plan are free.

From Video

POST /v1/mascots/{id}/animations/reference-video uses Premium at 6 credits per output second plus 1 credit for the pose image. Choose 4–30 whole seconds; the default 5 seconds costs 31 credits. Uploading the source video and first frame has no generation credit charge.

Check your balance

In the terminal, run masko credits or masko credits --json. Both SDKs expose Masko.client().credits(); await its result (try await in Swift). masko whoami also identifies the account and workspace associated with the balance.

curl https://api.masko.ai/v1/credits \
  -H "Authorization: Bearer $MASKO_API_KEY"

{
  "data": {
    "subscription": 450,
    "topup": 100,
    "total": 550
  }
}

The balance is scoped to the authenticated account or workspace. Subscription credits are used before top-up credits. Purchase credits and view current terms in Billing; generation credits and asset-hosting usage are separate charges.

Buy credits from an API or agent

Create a Stripe-hosted checkout for the workspace selected by your credential. This creates a payment page; it does not charge a saved card or enable automatic purchases. Personal purchases use your own balance. Team purchases require the active team owner, even when another member has generation permission.

curl https://api.masko.ai/v1/credit-checkouts \
  -H "Authorization: Bearer $MASKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: credit-purchase-001" \
  -d '{"amount_cents":2000}'

amount_cents is a whole-cent USD amount from 1000 to 1000000 ($10 to $10,000). Do not send an organization ID, price, credit quantity, payment method, or return URL. Masko derives the workspace from authentication and calculates credits using its current pricing. The response includes id, url, credits, amount_cents, currency, organization_id, expires_at, and status_url.

Open url and confirm the final amount on Stripe, including any taxes or discounts. Never send card details to an agent. Reuse the same Idempotency-Key and identical body after a timeout; responses replay for 24 hours. Check status if the returned checkout URL has expired before creating a new purchase.

curl https://api.masko.ai/v1/credit-checkouts/CHECKOUT_ID \
  -H "Authorization: Bearer $MASKO_API_KEY"

Only the user who created the checkout can read it, using the same workspace. The response separates payment_status from credits_added. A paid checkout with credits_added: false is awaiting credit delivery; check again rather than paying twice. balance is the current workspace balance, not a payment receipt. Reading checkout status never grants credits. Stripe's verified payment webhook records the grant once, including for delayed payment methods.

Connected agents expose these operations as create_credit_checkout (with amount_cents and a stable UUID operation_id) and get_credit_checkout (with id). Create checkout only after the user asks to buy credits. These tools provide a hosted checkout link, not an embedded or automatic Muse payment flow.

Approve a plan

For canvas generation, inspect a dry-run and submit the same selection, approved plan ID, and graph hash. These checks prevent a changed graph from silently increasing the approved work.

Credits are allocated when work is accepted. A timeout in your client does not prove that the request failed; inspect the accepted job or run before retrying. Use persisted idempotency keys on endpoints that support them. The general /generate endpoint does not provide the same run-level replay contract.

Insufficient credits

A rejected request returns HTTP 402:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "details": {
      "required": 21,
      "balance": 5
    }
  }
}

Read error.code and the details actually returned by the endpoint; wording and optional detail fields can differ.

Failures and refunds

Inspect the job or run before retrying. A partially failed run can still contain successful paid assets. Where available, runs report allocated_credits, credits_refunded, and refund_status; a missing refund value is not a promise of a pending refund.

If a source video succeeded but transparent format processing failed, reuse that source through media repair. Generating the video again would be a new paid operation. See generation and recovery for the CLI workflow.

Direct agent payment sandbox

For local integration testing, POST /v1/credit-payments accepts an amount_cents and payer-issued shared_payment_token, with an Idempotency-Key header. It attempts a Stripe test payment. Obtain the user's approval through the payer wallet first; never ask them to paste payment tokens into a chat. The API selects the workspace from authentication, and team purchases require the active owner.

The endpoint uses the same base USD credit pricing as hosted checkout, but does not calculate taxes or apply discounts. GET /v1/credit-payments/:id returns payment status and credits_added. Credits are delivered only by the dedicated verified sandbox webhook. A successful payment can precede credit delivery.

This experimental endpoint requires local Supabase and explicit Stripe sandbox configuration. It is unavailable in production and is not an MPP endpoint or a confirmed Muse payment integration. Continue using /v1/credit-checkouts for hosted purchases. If a payment outcome is uncertain, keep the same idempotency key and request; do not automatically start a new purchase.