Best practices

A few patterns that keep partner integrations boring and reliable. Use the interactive examples below as a starting point; swap the handle, slug, and instruction for your account.

Prefer a Format over raw model calls

When you have a saved recipe, call it by handle and slug. The Format owns the tooling, spend gates, and house style — your client only sends the brief.

See Calling a Format for the full contract, and Structured output when you need typed JSON back.

Bind a schema when a system will consume the result

If another service will read the receipt, bind output_schema so you get a validated object instead of free text. Require only fields the Format actually produces.

Full rules: Structured output.

Use Agent Completions for one-off work

When there is no saved Format yet — or the brief changes every time — send an Agent Completion with a spend cap.

Keep credentials scoped

Use a team API key for Formats provisioned on a team handle. Prefer the narrowest scopes your client needs, and rotate keys from the Dashboard.

Cap spend on every run

Always set generation_spend_cap_usd (and an agent cap when relevant). Treat missing caps as a bug in the client, not a convenience.