Generation allowance and usage

Check before generating

GET /api/v1/creatives/allowance requires a live campaigns:read key or owner session. No query parameters are accepted. It returns jobs_used, jobs_limit, jobs_remaining, enabled, available, service_capacity_available and checked_at. This read cannot generate, reserve a slot, or start queued jobs. The snapshot is advisory: creation checks capacity atomically again.

Policy included_spend_v1 includes 10 starter jobs per workspace, plus one job per 125 cents ($1.25) of eligible recorded campaign service fees. At a 5% service fee, this is approximately $25 of media spend per additional job; cent rounding applies. There is no additional generation charge or advertising-credit debit. Earned jobs are consumed before starter jobs. Workspace usage is cumulative (period=lifetime, resets_at=null), not a monthly subscription.

Eligible fees are reconciled against verified balance-funded live campaigns, with matching approval and allocated payment costs and no billing review. Deposits, budget reservations, sandbox campaigns, unverified costs and legacy direct campaign funding do not earn jobs. These are recorded fees, not final invoices. Corrections can reduce unused allowance; jobs already used remain counted. A funding hold blocks new generation, while saved jobs and exact original-request recovery remain accessible.

The service accepts at most 100 new jobs per UTC day and provides at most 100 starter jobs across all workspaces per UTC calendar month. Earned jobs bypass exhausted monthly starter capacity but still obey daily capacity. Other workspaces' usage counts are not exposed. Read blocked_reason, service_resets_at and retry_after_seconds; retry the same request only after temporary capacity resets. An exhausted workspace allowance has no timed reset: reuse stored creatives until eligible fee activity replenishes it.

One original generation or revision consumes one slot, including failed and uncertain attempts. A job supports one to three image variants. Reusing the exact request key/body returns the original job without consuming another slot. Publishing stored images uses no generation slot. This allowance is bounded and never authorizes new ad spend.

customer_charge_cents is zero under these terms. The models incur costs for MarketingRouter; included generation is funded from the existing 5% campaign service fee, which accrues only on media spend.

Find earlier generations

GET /api/v1/creatives returns ten jobs in data.items and data.next_cursor. Pass the cursor as ?cursor=UUID until next_cursor is null. Jobs are ordered by created_at and then UUID, both descending, so identical timestamps do not skip jobs. Cursors must belong to the authenticated workspace. Unknown, invalid or duplicate query parameters are rejected. Restart the first page to see newly created jobs. Selecting a saved job through GET /api/v1/creatives/{id} refreshes its signed image previews. Existing jobs remain readable when new generation is disabled.

Read model usage

GET /api/v1/creatives/{id} includes usage.accounting for newly processed jobs. Older records return null: historical image usage cannot be reconstructed safely from image dimensions or copy tokens.

• calls records the planned copy and image calls. Each moves from not_started to started before the potentially billed request, then observed when usage returns.
• input/output tokens and the image/text input split remain null when unavailable; they are never invented as zero.
• estimated_total_cost_usd is populated only when all planned calls have complete, priceable usage. It is USD major units.
• observed_estimate_usd adds only the priceable observed calls. For a partial job this is an incomplete subtotal, not its total cost or an upper bound.
• pricing_version pins the standard OpenAI rates used at observation. The estimate excludes account-specific discounts, regional premiums and taxes. It is not a settled invoice, customer charge or advance quote.
• provider_cost_usd remains null because response token usage does not establish a settled bill. Existing input_tokens/output_tokens fields continue to describe the copy call; use accounting.calls for images.

Copy-only revisions record only a new copy call; image-only revisions record only their new image call. Reused source assets are not counted again. Image usage is saved before byte validation or upload, so a storage failure does not erase observed cost. Missing responses remain started/partial even after the worker stops. Neither a timeout nor a missing image authorizes an automatic paid retry.

Standard rates verified October 3, 2026: OpenAI pricing, image usage and caching. Direct Images requests do not use cached-input discounts. Estimates are informational; no receipt or advertising wallet amount is changed by these reads.