This page covers the full generation lifecycle: start a job, check the cost, poll until it is done, and read the result. It also covers the options that shape the output.
Generation needs a key with Generate permission. Polling job status needs Read. See Create an API key.
How generation works
Generations run in the background. The start call returns a job, not an image. The image or video appears on the canvas a few seconds later. Poll the job to know when.
Start the job
POST to the generate endpoint. The response holds a jobId, the placeholder
object(s) created on the canvas, and the cost.
Poll the job
GET the job by its jobId every few seconds until status is completed (or
failed).
Read the result
On success the image is already on the canvas. Its URL is in the job’s resultUrls.
It appears the next time you read canvas state.
Reload-safe by design. The placeholder object is saved to the canvas before the job is queued. The result swaps in when it is ready. If your script crashes mid-generation, list in-flight jobs (see Recovering jobs) and continue from there.
Check the cost first
Run any generate request as a dry run by adding ?dry_run=true. Nothing is spent
and nothing is created. You get the estimate:
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 red apple", "provider": "flux2flash", "resolution": "hd" }'
{ "dryRun": true, "estimatedCost": 2, "balance": 200, "wouldSucceed": true, "reason": null }wouldSucceed is true regardless of your unit balance.Generating an image
The only required field is a prompt, either inline as prompt or as a canvas prompt
block via promptObjectId.
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",
"provider": "nanobanana2",
"aspectRatio": "16:9",
"resolution": "hd",
"count": 1
}'
{ "jobId": "7c1e...", "placeholderIds": ["a91f..."], "estimatedCost": 16, "status": "pending" }Options:
| Field | What it does |
|---|---|
prompt / promptObjectId | Your prompt text, inline or from a canvas prompt block. One is required. |
provider / model | Model to use (see Providers). Defaults to NanoBanana 2. |
aspectRatio | auto, 1:1, 4:3, 16:9, 9:16, etc. Defaults to auto. |
resolution | sd or hd. Defaults to hd. Affects cost. |
count | Amount of outputs (1–10). |
inputObjectIds | Canvas image objects used as input (image-to-image). Up to 10. |
smartRefIds | Smart refs to keep a character or style consistent. Up to 5. |
position | Placement of the result, e.g. { "x": 200, "y": 0 }. This is a center coordinate. |
idempotencyKey | A UUID you choose. Sending the same one twice returns the original job. There is no second charge. |
Prompt tags and smart refs work in the prompt itself
The prompt text goes through the same resolver as a submit in the browser. Two shorthands work here as well:
--m,--arand--qtags set model, aspect ratio and quality from inside the prompt:a red apple --m FLX2P --ar 16:9 --q hd. A tag beats the matching field in your request body. The response reports what won inappliedPromptTags.{SmartRefName}citations resolve against the same smart refs a person can see. You can name a ref inline instead of passing its id insmartRefIds.
Image-to-image and modes
When you pass inputObjectIds, the mode is derived automatically:
- No inputs → text-to-image.
- Inputs, with
countmatching the number of inputs → sequence: each input gets its own variation. - Inputs otherwise → group: the inputs are combined into each result.
Set mode explicitly (text, sequence, group) to override that. Sequence mode
multiplies the cost by the number of inputs.
Sequence results can land on top of each other. Each output is placed using its own width times its index, not the running total of the widths before it. A narrow result following a wide one can sit entirely inside the wide one’s footprint. If your outputs vary in shape, place them yourself afterwards.
Generating a video
Video uses a separate endpoint and always needs a provider and a duration:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate-video" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A drone shot flying over a misty forest at dawn",
"provider": "seedance2",
"duration": 5,
"resolution": "hd"
}'
The mode is derived from how many inputs you pass:
| Mode | Inputs | Notes |
|---|---|---|
video_text | none | Prompt only. |
video_image | 1 image | Animates a still. The image is the start frame. |
video_bookend | 2 images | First and last frame. |
video_reference | up to 9 images/videos | Every input is a reference, not a frame. |
video_video | 1 video | Edits an existing clip. The input must be a video object. |
Inputs beyond the frames a mode needs become reference images, where the provider supports them.
Video providers and their duration ranges:
provider | Model | Duration | Notes |
|---|---|---|---|
kling3 | Kling 3.0 | 3–15s | |
klingo1 | Kling O1 | 3–10s | Not edit-only. Serves start frame, bookend, references and clip edit. With an image input it accepts only 5 or 10 seconds. |
seedance15 | Seedance 1.5 | 4–12s | |
seedance2 | Seedance 2.0 | 4–15s | |
seedance2mini | Seedance 2.0 Mini | 4–15s | |
minimaxh3 | MiniMax H3 | 5–15s | No audio control. Native stereo is always on. The floor is 5, not 4. A 4 is rejected. |
Video takes longer than images: tens of seconds, sometimes a couple of minutes.
Poll the job the same way. ?dry_run=true works here too.
Polling the job
Every job is polled the same way:
curl "https://derived.pro/api/cli/canvases/<canvasId>/jobs/<jobId>" \
-H "Authorization: Bearer paste-your-key-here"
{
"id": "7c1e...",
"status": "completed",
"prompt": "A serene mountain landscape at sunset",
"provider": "nanobanana2",
"aspectRatio": "16:9",
"resolution": "hd",
"mode": "text",
"unitCost": 16,
"generationTimeMs": 8420,
"resultUrls": { "a91f...": "https://.../result.png" },
"resultObjectIds": ["a91f..."],
"inputImageIds": [],
"createdAt": "...",
"completedAt": "..."
}A finished job reports what it cost (unitCost), which objects it produced
(resultObjectIds), what it consumed (inputImageIds), and how long it took. Array
fields are omitted when empty, not sent as []. On a failure you also get
errorCategory alongside errorMessage.
status moves through pending → processing → completed. If it ends in failed,
errorMessage explains why in plain language. Any units are refunded automatically.
Poll every few seconds, not more often.
Recovering jobs
To find running jobs after a restart, list the canvas’s jobs. By default the in-flight ones are returned:
curl "https://derived.pro/api/cli/canvases/<canvasId>/jobs" \
-H "Authorization: Bearer paste-your-key-here"
Add ?status=all or a comma-separated list like ?status=pending,completed to
broaden it.
Prompts and variables
Instead of an inline prompt, point a generation at a prompt block on the canvas and fill in its placeholders. This templates a series of variations.
Given a prompt block whose text is A <color> apple on a wooden table:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/generate" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "promptObjectId": "<promptObjectId>", "variableValues": { "color": "green" } }'
Supply values inline with variableValues, or point at variable blocks on the canvas
with variableObjectIds. They fill in by name. See
Canvases & objects for how prompt and
variable blocks are created.
Smart refs (consistent characters & styles)
A smart ref is a named set of reference images attached to a generation. It keeps
a character, product, or style consistent across many results. Pass their IDs as
smartRefIds.
Smart refs can be managed through the API. They are built from images already on the canvas but are project-scoped. Listing them from a canvas returns every ref you can cite by name from that canvas, including refs that live elsewhere in the project.
Editing is narrower than citing. Each listed ref carries a manageable flag.
manageable: false is the normal state for a project-level ref. You can use it in a
prompt, but you cannot rename, delete, or add images to it through this canvas. The
row tells you which canvas to address it from, or null for a project-level ref that
only a person can curate in the app.
Create a smart ref
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/smart-refs" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Mascot", "canvasObjectIds": ["<imageObjectId>"] }'Add more reference images
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/smart-refs/<smartRefId>/images" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "canvasObjectIds": ["<anotherImageObjectId>"] }'Use it in a generation
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": "The mascot waving on a beach", "smartRefIds": ["<smartRefId>"] }'List them with GET https://derived.pro/api/cli/canvases/<canvasId>/smart-refs.
Regenerating and tidying up
Regenerate
Re-run an image’s saved recipe (same prompt, inputs, and settings) with optional overrides. The object must be a generated image:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/regenerate" \
-H "Authorization: Bearer paste-your-key-here" \
-H "Content-Type: application/json" \
-d '{ "resolution": "hd", "count": 2 }'
You can override prompt, resolution, aspectRatio, and count. It costs units
like any generation.
Remove a background
Strips the background from an image. It is an async job (2 units) that produces a new transparent image:
curl -X POST "https://derived.pro/api/cli/canvases/<canvasId>/objects/<objectId>/remove-background" \
-H "Authorization: Bearer paste-your-key-here"
The response holds a jobId. Poll it at
https://derived.pro/api/cli/canvases/<canvasId>/removal-jobs/<jobId> until it is completed.
Providers, resolution, and aspect ratios
A provider is named by its internal name or its short display code:
| Provider | Code | Notes |
|---|---|---|
| NanoBanana | NNBN | |
| NanoBanana 2 | NNBN2 | Default. |
| Seedream 4.5 | SDRM | In text mode, needs an explicit aspectRatio (not auto). |
| Seedream 5 Pro | SDRM5 | Also the engine behind layerize. |
| FLUX2 (Dev / Flash / Pro / Klein) | FLX2, FLX2F, FLX2P, FLX2K | |
| GPT Image 2 | GPTI2 | HD costs much more than SD. |
Resolution is sd or hd. HD costs more than SD. The exact unit cost varies by
provider. Aspect ratio accepts auto plus common ratios (1:1, 4:3, 3:4,
16:9, 9:16, 3:2, 2:3, 21:9, …).
Prompt length
Prompts are capped. The check runs before anything is charged. An over-long prompt
is a 400, and no unit is spent.
| Cap | |
|---|---|
| Every image model | 5,000 characters |
| Seedance (all three) | 5,000 characters |
| Kling 3.0 and Kling O1 | 2,500 characters |
| MiniMax H3 | 2,000 characters |
The cap applies to the resolved prompt, after variables are substituted and any
{SmartRef} names are expanded into their full descriptions. A prompt that looks
short as written can land over the limit. Switching model only lowers the ceiling,
never raises it.
Checking prices
GET https://derived.pro/api/cli/pricing returns the whole current price list in one call:
curl "https://derived.pro/api/cli/pricing" \
-H "Authorization: Bearer paste-your-key-here"
It is the live server-side catalogue, the same module that prices the actual charge.
It cannot drift from what you are billed. Use it to plan. Use dry_run to price one
specific job. A dry run accounts for sequence expansion, which a price list does not.
Run a dry_run if cost matters. It reports the exact units for the provider,
resolution, mode, and count you chose. New workspaces start with 50 units.
Every endpoint and field is listed in the API reference.