Pricing & limits

Dream Engine charges a flat $0.0005 per generated frame for every customer, paid out of a prepaid credit balance topped up via Stripe Checkout. No tiers, no commitments, no warm-pool minimum.

Per-frame pricing

A canonical DreamDojo · GR-1 rollout (48 action frames, 49 frames billed including the conditioning frame) costs $0.0245. A K=8 visual-MPC batch on the same starting frame is 8 × $0.0245 = $0.196.

Prepaid credits

Every API key has a credit balance, denominated in USD. Each successful predict pre-debits the expected cost from the balance and refunds on engine error. Insufficient balance returns HTTP 402 before any GPU work fires — you never get charged for a request that didn't run.

import dream
 
client = dream.Client()
 
# Check your balance.
b = client.billing.balance()
print(f"${b.balance_usd:.2f} ({b.balance_cents} cents)")

Top-ups

Add credits with a one-time Stripe Checkout payment. The SDK returns a hosted Checkout URL — open it in a browser to complete the payment.

session = client.billing.topup(amount_usd=25.00)
print("Open this in a browser to pay:", session.url)

Bounds: $5 minimum, $10,000 maximum per top-up. Payments settle synchronously: once Stripe confirms, the engine's webhook fires and your balance is updated. The next predict call sees the new balance.

There's no monthly subscription. No auto-renew. You pay when you want to, in increments you choose.

Cost on the response

Every rollout response carries the actual cost in the X-DreamEngine-Estimated-Charge-USD header, surfaced as cost_usd:

rollout = model.predict(start_frame=img, actions=acts)
print(rollout.cost_usd)        # e.g. 0.0245 (49 × $0.0005)
print(rollout.request_id)      # request UUID — keep for audits

cost_usd is computed as frames × $0.0005 on the server. The matching debit on your credits balance is the same number, rounded up to the nearest integer cent (Stripe charges in cents, so $0.0245 debits 2 cents).

Insufficient credits → 402

When your balance can't cover the predicted cost, the engine returns 402 before invoking the model. The SDK raises a typed dream.InsufficientCreditsError carrying both the current balance and the requested amount in cents:

import dream
 
try:
    rollout = model.predict(start_frame=img, actions=acts)
except dream.InsufficientCreditsError as e:
    print(f"balance: ${e.balance_usd:.4f}")
    print(f"needed:  ${e.requested_usd:.4f}")
    session = client.billing.topup(amount_usd=25.00)
    print("Top up here:", session.url)

Refunds

You don't get charged for work the engine couldn't deliver:

• Engine errors (anything 5xx, runner crash, malformed output) — the pre-debit is automatically refunded before the response leaves the server.
• Frame undercount — if the engine returns fewer frames than predicted (chunk-pad-trim corner cases), the difference is refunded in cents on the same response.

You don't see the refund in the SDK; it's reconciled server-side and reflected in the next client.billing.balance() call.

Rate limits

The credits ledger is the primary throttle — every predict pre-debits the cost and 402s if the balance can't cover it. The per-key token bucket on top is a sanity floor (catches runaway scripts before they saturate a container); it's invisible for normal use.

Default rate-limit knobs on a fresh key: 50 qps refill, 200 burst. That's well above any plausible interactive workload. If you're hitting it (real-time MPC at >50 req/sec sustained from one key), email hello@dreamengines.run and we'll dial it up.

When the bucket empties, the engine returns 429 with Retry-After. The SDK retries automatically; if retries exhaust, you get dream.RateLimitError with e.retry_after.

Receipts

Every rollout response carries an X-DreamEngine-Request-Id header (also surfaced as rollout.request_id). Save these in your own logs — they're the audit join key against your credits ledger.

To audit your spend, call client.billing.balance() periodically; the delta between balances is what you spent in the interval. Per-rollout breakdown lives in your application logs (we don't ship a hosted billing dashboard yet).

Pricing notes

• The price applies to generated frames, not action frames. A 48-action rollout produces 49 frames (the start frame is conditioning + counted as the first generated frame); you pay for 49.
• The dreamengine-2b-gr1 catalog entry's price_per_frame_usd is the same $0.0005 — the catalog reflects the live wire price.
• We're not running tiered pricing today. If you need volume terms (tens of millions of frames per month), email and we'll figure it out per-customer rather than via a self-serve discount tier.