Your own script or integration can call the derived API directly, without an AI assistant. It is a plain HTTP/JSON API. Any language that can make an HTTP request can use it.
To let an assistant drive instead, see Connect an AI assistant. It uses the same key and the same permissions, and discovers the API for you.
What you’ll need
- An API key — see Create an API key. It is sent as a bearer token on every request.
- The base URL for the API:
https://derived.pro/api/cli
Every path below is relative to that base. For example, listing canvases is a GET
to https://derived.pro/api/cli/canvases.
Authentication
Send your key in the Authorization header as a bearer token on every request:
curl "https://derived.pro/api/cli/canvases" \
-H "Authorization: Bearer paste-your-key-here"
Three things to know:
- Keys are scoped. Each key carries some combination of Read, Write, and Generate permission. A request without the matching permission returns a permission error. See Create an API key.
- One workspace per key. A key reaches every canvas in the workspace it was created under. It cannot see other workspaces.
- Keep it secret. Treat the key like a password. If it leaks, revoke it on the API Keys page and create a new one.
Never put your key in client-side code or a public repo. Anyone with the key can act in your workspace until you revoke it.
The core loop
Almost every task follows the same shape:
Find a canvas
List your canvases, or create one. Read its state to see the objects on it.
Add or arrange objects
Upload images, add text, add prompt and variable blocks, or move objects.
Generate
Start an image or video generation. It runs in the background and spends units (unless you've connected your own Fal.ai key).
Poll the job
A generation returns a job, not the image. Check the job status until it is
completed. The result lands on the canvas.
Two pages cover each half in detail:
The data model and how to create, read, move, and delete objects.
🧱 Canvases & objectsStart a generation, poll the job, read the result, and check cost first.
🪄 Generating images & videoQuickstart
The whole loop end to end. Replace paste-your-key-here and the placeholder IDs
with real values.
List your canvases
curl "https://derived.pro/api/cli/canvases" \
-H "Authorization: Bearer paste-your-key-here"The response is a list of canvases, each with an id. Pick one as <canvasId>.
Check the cost of a generation
Add ?dry_run=true to a generate request. derived returns the estimated
cost and your balance without spending anything:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate?dry_run=true" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "A serene mountain landscape at sunset", "aspectRatio": "16:9" }'The response looks like:
{
"dryRun": true,
"estimatedCost": 16,
"balance": 200,
"wouldSucceed": true,
"reason": null
}Start the generation
Without the dry_run flag the same request runs. The response is a job:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "A serene mountain landscape at sunset", "aspectRatio": "16:9" }'{
"jobId": "7c1e...",
"placeholderIds": ["a91f..."],
"estimatedCost": 16,
"status": "pending"
}Poll until it’s ready
Use the jobId to check the job. Repeat every few seconds until status is
completed:
curl "https://derived.pro/api/cli/canvases/<canvasId>/jobs/<jobId>" \
-H "Authorization: Bearer paste-your-key-here"When done, the result image is on the canvas. Its URL is in resultUrls. Read the
canvas state again to see it in place.
Errors and limits at a glance
Every error returns the same JSON shape and a matching HTTP status code:
{ "error": { "code": "VALIDATION_ERROR", "message": "aspectRatio must be one of …" } }| Status | Code | What it usually means |
|---|---|---|
| 400 | VALIDATION_ERROR | A field in the request body is missing or invalid. |
| 401 | UNAUTHORIZED | Missing, invalid, or revoked key. |
| 403 | FORBIDDEN | The key lacks the permission this endpoint needs. |
| 402 | PAYMENT_REQUIRED | Not enough units for this generation. |
| 404 | NOT_FOUND | The canvas, object, or job does not exist, or your key cannot see it. |
| 409 | CONFLICT | The resource changed since you read it (e.g. an edit version mismatch). |
| 429 | RATE_LIMITED | Too many requests. Wait for the seconds in the Retry-After header, then retry. |
Requests are rate-limited per workspace, in three buckets: reads, writes, and
generations. On a 429, wait the number of seconds in the Retry-After header
and try again.
The full list of endpoints, with a curl example for each, is in the API reference.