MotionLab for developers

AI image generation and editing API

Build image generation and reference-image editing with live model settings and fractional-credit pricing.

Text-to-image and reference-image editing

Use text-to-image to create a new composition from a prompt. For an edit, upload your source images and pass their owned keys in referenceImageKeys. The selected model determines how many references are supported and which output settings can be combined.

The live image model catalog provides current choices. In an integration, read result.models.image from GET /api/v1/models and select the exact modelId. Do not infer a model ID from its display name or copy a provider endpoint ID without checking discovery.

Request only the settings the model supports

Image models can expose aspect ratios, resolutions, quality choices and output formats. A value that works for one model may fail on another. Start with the model defaults, then add supported settings one at a time. For product catalogs, keep the aspect ratio and background direction consistent across requests.

POST /api/v1/actions/motionlab_generate_image
{
  "model": "IMAGE_MODEL_ID_FROM_DISCOVERY",
  "prompt": "Studio product photograph on a soft neutral background",
  "idempotencyKey": "YOUR_SAVED_UNIQUE_REQUEST_ID"
}

POST /api/v1/actions/motionlab_generate_image
{
  "model": "EDIT_CAPABLE_MODEL_ID_FROM_DISCOVERY",
  "prompt": "Keep the product shape and label; replace the background with warm stone",
  "referenceImageKeys": ["OWNED_UPLOAD_KEY"],
  "idempotencyKey": "YOUR_SAVED_UNIQUE_EDIT_ID"
}

Send the JSON body with Bearer authentication. Create the owned reference key using motionlab_create_upload and finish the upload before submitting the edit. Check the reference limit before building a multi-image request.

Understand fractional-credit image pricing

A generation can cost less than one credit. Your application should preserve the returned decimal amount when displaying estimates and balances, rather than rounding every request up to a whole credit. The model, resolution and edit mode can affect the cost.

Call motionlab_estimate_cost with kind: image and the selected model. Include hasReferenceImages: true for an edit and inspect the returned assumptions. Estimates are not reservations; the generation service checks the final request price when it creates the job.

POST /api/v1/actions/motionlab_estimate_cost
{
  "kind": "image",
  "model": "EDIT_CAPABLE_MODEL_ID_FROM_DISCOVERY",
  "hasReferenceImages": true
}

Take an image workflow into production

Use one persisted idempotency key per intended image. Keep retry attempts attached to the same key and save result.jobId for polling. Your interface can then recover the result after a browser refresh without submitting and paying for another image.

When the job completes, download outputUrl to storage you control. Validate the result against your use case: product geometry, label legibility, composition and reference consistency matter more than the model name alone. New creative variations should use new request IDs.

To animate a result, inspect the job's reusableAs information and use startImageJobId where supported. The video API guide explains duration, upload and polling decisions for the next stage.

Continue building

Explore live models and prices · Create your API key

AI image generation and editing API | MotionLab