Core concepts

Idempotency

Retry generation requests safely with the Idempotency-Key header.

How it works

Expensive generation POSTs accept an optional Idempotency-Key header (up to 255 characters): the async job creators (/videos, /songs, /code-builds, /research, which return a 202 job envelope) and the synchronous creators (/images, /extract-flowchart, which return the finished result directly, no job). When the header is present, the response is cached per key: a retry with the same key replays the original response (the same jobId for async endpoints, the same finished result for sync ones) instead of running a second billed generation.

Example

curl

curl https://www.opencharts.com/api/v1/videos \
  -H "Authorization: Bearer $OPENCHARTS_API_KEY" \
  -H "Idempotency-Key: order-42-video" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A drone shot over a neon city at dusk" }'

Guarantees

Keys are scoped per account and per endpoint, so the same key on two different endpoints never collides. Cached responses replay for 24 hours. The guarantee targets sequential retries (the network-blip case); two truly concurrent requests with the same key can still both run.