Best practices

This page gives a few patterns that keep partner integrations stable and reliable. Use the interactive examples below as a start. Replace the handle, the slug, and the instruction with the values for your account.

Prefer a Format over raw model calls

When you have a saved recipe, call the recipe by its handle and slug. The Format owns the tools, the spend gates, and the house style. Your client only sends the brief.

curl -sS -X POST "https://api.sume.com/v1/formats/chase/my-format/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"instruction":"Make two ad images for the linked product.","input":{"product_url":"https://example.com/p"}}'

For the full contract, refer to Calling a Format. When you must get typed JSON back, refer to Structured output.

Bind a schema when a system will consume the result

If another service will read the receipt, bind output_schema. Then you get a validated object, not free text. Mark a field as required only if the Format actually produces that field.

Full rules: Structured output.

Use Agent Completions for one-off work

If there is no saved Format or the brief changes each time, send an Agent Completion with a spend cap.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"instruction":"Make two product stills from https://example.com/p and summarize what you shot.","generation_spend_cap_credits":400}'

Keep credentials scoped

For Formats that are provisioned on a team handle, use a team API key. Select the narrowest scopes that your client needs. Rotate keys from the Dashboard.

Cap spend on every run

Always set generation_spend_cap_credits (and an agent cap when applicable). A missing cap is a bug in the client, not a convenience.