From idea to API call.

Your first request

Create an account and an API key, then send a request. The playground uses the same API with your signed-in account.

1export MADEBYCUE_URL="http://localhost:3000"2export MADEBYCUE_API_KEY="cue_YOUR_API_KEY"

1curl -X POST "$MADEBYCUE_URL/api/v1/tasks" \2  -H "Authorization: Bearer $MADEBYCUE_API_KEY" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: my-first-request-001" \5  -d '{6  "task": "image.generate",7  "prompt": "An amber glass bottle on pale stone, soft morning light, room for a headline.",8  "aspect_ratio": "16:9",9  "reference_images": [10    "https://your-site.com/bottle.jpg"11  ]12}'

New tasks return 202 Accepted. A retry with the same body and idempotency key returns the original task with 200 OK. Generation takes seconds to minutes: poll GET /api/v1/tasks/{id} until status is succeeded, failed, needs_input, or planned (dry runs only). Tasks survive disconnects; nothing is lost if you stop polling.

1{2  "id": "task_…",3  "request_id": "req_…",4  "task": "image.generate",5  "prompt": "An amber glass bottle on pale stone, soft morning light, room for a headline.",6  "output_type": "image",7  "status": "queued",8  "classification": null,9  "request": {10    "task": "image.generate",11    "prompt": "An amber glass bottle on pale stone, soft morning light, room for a headline.",12    "aspect_ratio": "16:9",13    "reference_images": [14      "https://your-site.com/bottle.jpg"15    ]16  },17  "outputs": [],18  "cost": {19    "currency": "USD",20    "estimated": 0.5,21    "charged": 0.5,22    "credits_charged": 5023  },24  "message": "Queued for execution.",25  "created_at": "2026-10-01T12:00:00.000Z",26  "expires_at": "2026-10-02T12:00:00.000Z"27}

1// Run on your server; never expose the API key in browser code.2const idempotencyKey = crypto.randomUUID(); // Keep this key for retries.3const response = await fetch(process.env.MADEBYCUE_URL + "/api/v1/tasks", {4  method: "POST",5  headers: {6    Authorization: "Bearer " + process.env.MADEBYCUE_API_KEY,7    "Content-Type": "application/json",8    "Idempotency-Key": idempotencyKey,9  },10  body: JSON.stringify({11  "task": "image.generate",12  "prompt": "An amber glass bottle on pale stone, soft morning light, room for a headline.",13  "aspect_ratio": "16:9",14  "reference_images": [15    "https://your-site.com/bottle.jpg"16  ]17}),18});19const result = await response.json();20if (!response.ok) throw new Error(result.error.message);21console.log(result.id, result.request_id, result.cost);22// Poll GET /api/v1/tasks/{id} until status is succeeded, failed, needs_input, or planned.

Authentication

Pass Authorization: Bearer [REDACTED]. Create and revoke keys in API keys. Keys are hashed at rest and new keys expire after 90 days. Keep them on your server. The playground uses a same-origin Better Auth session.

Every task and log is scoped to the authenticated account. A task ID or request ID alone does not grant access.

Create a task

POST /api/v1/tasks accepts JSON. Pick one of four tasks. There is no public model selector: the router chooses the execution backend.

Unknown fields are rejected, and so are fields that are meaningless for the chosen task: aspect_ratio on video tasks and duration_seconds on edits return 400 instead of being silently ignored. Send at most 20 KB of JSON. URLs must use HTTPS and a public hostname, with no username or password.

Tasks are charged on acceptance: 50 credits for image tasks ($0.50), 300 for video generation ($3.00), 500 for video edits ($5.00). Failed tasks and needs_input tasks are refunded automatically. Dry runs are free.

Give each input a purpose

References guide the look or subject. Sources are assets to edit. The start frame anchors the opening of a new video. Use the prompt to explain the change you want.

Upload files in three steps using your session or API key: reserve with POST /api/media/request-upload (name, mime, size), PUT the bytes to the returned URL, then confirm with POST /api/media/confirm to get the /api/media/… URL for the task. One PNG/JPEG/WebP/MP4/ WebM up to 20 MB per upload; uploads are private to your account and expire after 24 hours. Linked public videos can be up to 200 MB; linked images up to 20 MB.

1{2  "task": "image.edit",3  "prompt": "Keep the candle and replace the background with warm ivory.",4  "source_image": "https://your-site.com/candle.jpg",5  "reference_images": [6    "https://your-site.com/mood.jpg"7  ]8}

1{2  "task": "video.generate",3  "prompt": "A smooth camera move from the product detail to the full scene.",4  "start_frame": "https://your-site.com/start.jpg",5  "duration_seconds": 56}

1{2  "task": "video.edit",3  "prompt": "Change the background to match the reference while preserving the product and camera movement.",4  "source_video": "https://your-site.com/clip.mp4",5  "reference_images": [6    "https://your-site.com/background.jpg"7  ]8}

Read, download & delete

GET /api/v1/tasks/{id} returns a task, its submitted request, cost, and expiry. GET /api/v1/tasks returns your latest 30 unexpired tasks in data.

1curl "$MADEBYCUE_URL/api/v1/tasks/task_YOUR_ID" \2  -H "Authorization: Bearer $MADEBYCUE_API_KEY"

Succeeded tasks list outputs with download URLs: GET /api/v1/tasks/{id}/outputs/{n} serves the mirrored file with the same authentication. needs_input carries the planner’s question in message; submit a revised task with a new idempotency key.

DELETE /api/v1/tasks/{id} removes the task, its logs, its mirrored outputs, and its backend execution. Delete stops tracking, not spending: already-submitted work is not cancelled or refunded.

Request logs & costs

View Request logs for your requests, status, cost, and time. Select a request to view its submitted JSON. The request ID is returned in both the body and X-Request-Id.

GET /api/v1/logs?limit=20 lists your logs, summary totals, and next_cursor. Pass it as cursor to retrieve the next page. The page size is 1–50. GET /api/v1/logs/{request_id} returns one log with its request, response summary, and events.

cost.estimated is the quoted task price. cost.charged is the USD amount actually charged and cost.credits_charged the matching credit amount; 100 credits = $1. Both drop to zero when a failed task is refunded. Retries create a diagnostic log but no second task or charge.

Authenticated POST attempts are logged, including validation errors, conflicts, and account rate-limit errors. Unauthenticated requests and read requests are not stored. Invalid bodies are discarded; only a safe error summary is retained. Authorization headers, cookies, and API keys are never copied into request logs. Avoid including secrets in prompts or media URLs.

Gone after 24 hours

Tasks and logs stop being readable at their expires_at timestamp. Background cleanup runs every minute and deletes expired database rows, uploaded and mirrored media, and backend executions, including prompts, input URLs, responses, and event details. Actual removal happens on the next successful cleanup run. Idempotent retries do not extend the original task’s expiry.

Credit balances and payment records are separate and do not expire with request logs. Database backups follow the hosting provider’s separate retention policy; deleting active rows does not erase earlier backups.

Errors & retries

Send a unique Idempotency-Key for each new task, then reuse that key and the same body when retrying a failed connection. Keys are 1–128 printable non-space ASCII characters. The idempotency window is 24 hours; after that, the same key can create a new task. If omitted, the server generates a key and cannot deduplicate your retries.