API reference

Authentication

Send Authorization: Bearer tk_…. A key acts as its creator inside one workspace. GET /v1/models and GET /v1/tools work without a key.

Endpoints

Creating takes

Headers

The take object

{
  "id": "lgmog4x1",
  "object": "take",
  "status": "succeeded",          // queued | processing | succeeded | failed
  "model": "nano-banana-2.1",
  "version": "2.1 (pinned)",
  "cost_usd": 0.053,
  "refunded": false,
  "error": null,
  "output": {
    "url": "https://edengen.ai/v1/takes/lgmog4x1/content",
    "mime_type": "image/png",
    "filename": "lgmog4x1_nano-banana-2.1_1K.png"
  },
  "simulated": false,
  "source": "api",                 // app | api | mcp
  "metadata": { "shot": "12A" },
  "created_at": "2026-10-18T09:54:11.882Z",
  "completed_at": "2026-10-18T09:54:20.804Z",
  "timings": { "total_s": 8.9 }
}

Model aliases

Give a model and its settings a name your pipelines hardcode, then send that name as model. Change the alias and every key, agent and pipeline follows without a deploy. Settings sent with a request win over the alias. Owners manage aliases in Settings or here.

curl -X POST https://edengen.ai/v1/aliases -H "Authorization: Bearer $TAKES_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "hero-video", "model": "seedance-2.5", "resolution": "1080p", "duration": 10, "aspect_ratio": "21:9"}'

curl -X POST https://edengen.ai/v1/takes -H "Authorization: Bearer $TAKES_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "hero-video", "prompt": "Slow push in on a lighthouse in a storm, no music"}'

Budgets by tag

Cap spend per client, campaign or environment. Tag takes with tags or the X-Takes-Tags header, then set a monthly budget for a tag. A take whose tags match is refused with 429 tag_budget before anything is charged when it would pass the budget. Budgets reset on the first of the month (UTC) and count net of refunds.

curl -X POST https://edengen.ai/v1/budgets -H "Authorization: Bearer $TAKES_API_KEY" -H "Content-Type: application/json" \
  -d '{"key": "client", "value": "acme", "cap_usd": 500}'

Delivery and observability

Add an S3-compatible bucket (AWS S3, Cloudflare R2, Backblaze, Google Cloud Storage interoperability) and every finished take is copied there as prefix/project/take-id_model_resolution.ext with a JSON sidecar of the prompt, model, cost and tags. Add an OTLP/HTTP endpoint and each take arrives as one span with its model, provider, cost, project and tags, refunds included. Deliveries retry with backoff; Settings shows the count and the last error. Secrets are encrypted and never returned.

curl -X POST https://edengen.ai/v1/exports -H "Authorization: Bearer $TAKES_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind": "s3", "name": "R2 renders", "endpoint": "https://<account>.r2.cloudflarestorage.com", "bucket": "renders",
       "access_key_id": "...", "secret_access_key": "..."}'

Draft, then finish

Render low-cost drafts, approve one, then POST /v1/takes/{id}/finish. The final keeps the prompt and framing, moves to the stronger sibling (Seedance 2.0 Mini to Seedance 2.0, Veo 3.1 Fast to Veo 3.1, Nano Banana 2.1 to Pro) at 1080p or 2K, and passes the draft as a reference so the composition holds. Name model or resolution in the body to choose yourself. A repeated call returns the same final and charges once. Agents use the takes_finish tool, which asks above your threshold.

Errors

{ "error": { "type": "budget_error", "code": "over_cap", "message": "Spot would go over its $3 cap ($1.19 spent)..." } }

Rate limits

Each key allows 120 requests per minute by default. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. There is no starting concurrency limit on renders.

Usage for re-billing

curl "https://edengen.ai/v1/usage?from=2026-10-01&to=2026-11-01&group_by=project" -H "Authorization: Bearer $TAKES_API_KEY"