Production integration
Build a recoverable integration with explicit costs, durable task tracking and useful diagnostics.
Choose a model and protocol
Read the authenticated live catalog, including inputSchema and examples, and require both enabled and available. Public model pages describe capabilities; they do not prove that your account can submit a request. Native tasks use /api/v1, while compatible clients use /v1. Console cookies are not API credentials.
Prepare input on your server
Keep the API key in your backend environment, outside browser bundles, mobile apps and public repositories. Follow the current schema types, enums and conditional requirements. For media input, you can use a publicly accessible HTTPS URL or a supported Base64 input as described in the media guide. For local file uploads, request a ticket, PUT the bytes and commit the file, then pass the returned spicy:// URI in the model-supported field. Validate again after switching models.
Quote before accepting a charge
Send the complete model, input and callBackUrl to jobs/quote. Show estimatedCost, maxCharge, currency and expiresAt to the person paying. A quote lasts five minutes and holds no funds. After confirmation, add quoteId and expectedCost to the same request. A changed input or 40901 requires a new quote; never silently accept a higher amount. Preserve decimal strings and use decimal arithmetic for reconciliation.
Persist the business operation
Before sending, save your operation ID, a safe request fingerprint and Idempotency-Key. Add taskId and request_id after acceptance. Reuse the original key for the same account, API key and logical submission within the 24-hour window. A timeout does not prove rejection. Recover the original submission before creating a new key. Retrying a terminal failure creates a new task at current conditions and prices.
Handle callbacks and results reliably
Verify the callback signature and timestamp against the original bytes, then deduplicate and persist the event. Acknowledge promptly and put slow work in your own queue. Handle duplicate and delayed notifications by task state. Use bounded exponential polling of recordInfo as a fallback. HTTP 202 means accepted; succeeded confirms generation, and settled=true confirms final billing.
Bound concurrency and retain results
Limit in-flight tasks per account and set request deadlines. Follow Retry-After on 429; avoid synchronized polling every second. Cache catalogs privately and briefly, and never treat a quote as a permanent price list. Download links last 20 minutes, generated media 14 days and uploads one day. Archive results you need to keep. Disconnecting does not cancel an accepted task.
Validate before launch
Start with catalog, balance and quote calls. Run a minimal generation through your own cost-confirmation flow, then check success, invalid input, insufficient balance, same-key recovery after timeout, duplicate callbacks, expired links and budget limits. Log request_id, taskId, time, state and amounts; keep keys and full prompts out of general logs.
Related workflows
Quotes and protocol compatibility · Model catalog and schemas · Media · Webhooks · Errors · Troubleshooting and recovery