Skip to Content
Agents & APIGenerating images & video

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 }
If you have connected your own Fal.ai key, generations are billed to that account instead of units. 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:

FieldWhat it does
prompt / promptObjectIdYour prompt text, inline or from a canvas prompt block. One is required.
provider / modelModel to use (see Providers). Defaults to NanoBanana 2.
aspectRatioauto, 1:1, 4:3, 16:9, 9:16, etc. Defaults to auto.
resolutionsd or hd. Defaults to hd. Affects cost.
countAmount of outputs (1–10).
inputObjectIdsCanvas image objects used as input (image-to-image). Up to 10.
smartRefIdsSmart refs to keep a character or style consistent. Up to 5.
positionPlacement of the result, e.g. { "x": 200, "y": 0 }. This is a center coordinate.
idempotencyKeyA 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, --ar and --q tags 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 in appliedPromptTags.
  • {SmartRefName} citations resolve against the same smart refs a person can see. You can name a ref inline instead of passing its id in smartRefIds.

Image-to-image and modes

When you pass inputObjectIds, the mode is derived automatically:

  • No inputs → text-to-image.
  • Inputs, with count matching 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:

ModeInputsNotes
video_textnonePrompt only.
video_image1 imageAnimates a still. The image is the start frame.
video_bookend2 imagesFirst and last frame.
video_referenceup to 9 images/videosEvery input is a reference, not a frame.
video_video1 videoEdits 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:

providerModelDurationNotes
kling3Kling 3.03–15s
klingo1Kling O13–10sNot edit-only. Serves start frame, bookend, references and clip edit. With an image input it accepts only 5 or 10 seconds.
seedance15Seedance 1.54–12s
seedance2Seedance 2.04–15s
seedance2miniSeedance 2.0 Mini4–15s
minimaxh3MiniMax H35–15sNo 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:

ProviderCodeNotes
NanoBananaNNBN
NanoBanana 2NNBN2Default.
Seedream 4.5SDRMIn text mode, needs an explicit aspectRatio (not auto).
Seedream 5 ProSDRM5Also the engine behind layerize.
FLUX2 (Dev / Flash / Pro / Klein)FLX2, FLX2F, FLX2P, FLX2K
GPT Image 2GPTI2HD 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 model5,000 characters
Seedance (all three)5,000 characters
Kling 3.0 and Kling O12,500 characters
MiniMax H32,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.