API reference

One endpoint, any pipeline.

Embellify exposes a small REST API. Authenticate with a key, post a product image, and poll (or get a webhook) for the in-scene result. Same engine as the studio.

Quickstart

Create your first generation:

curl https://app.embellify.com/api/v1/generations \
  --request POST \
  --header "Authorization: Bearer sk_live_…" \
  --header "Content-Type: application/json" \
  --data '{
    "image_url": "https://…/product.png",
    "situation": "on a marble counter, morning light",
    "aspect_ratio": "4:5",
    "webhook_url": "https://yourapp.com/hooks/embellify"
  }'

# → 202
# {
#   "job_id": "6a3d3322272d39a2deacbd55",
#   "status": "queued",
#   "cost_credits": 1
# }

Then poll for the result:

curl https://app.embellify.com/api/v1/generations/6a3d3322272d39a2deacbd55 \
  --header "Authorization: Bearer sk_live_…"

# → 200
# {
#   "job_id": "6a3d3322272d39a2deacbd55",
#   "status": "done",
#   "result_image_url": "https://…r2.dev/outputs/6a3d…55.png",
#   "input_image_url": "https://…r2.dev/inputs/df1f…98.webp",
#   "model": "google-nano-banana",
#   "aspect_ratio": "3:4",
#   "cost_credits": 1,
#   "error": null,
#   "created_at": "2026-06-25T13:54:42.825Z"
# }

A job moves through queued → processing → done → failed. Poll until done (theresult_image_url is then set) orfailed — a failed job is refunded automatically.

Authentication

Create a key in Settings and send it as a bearer token, or as an x-api-key header. Live keys are prefixed sk_live_.

Endpoints

POST/api/v1/generationsCreate a generation. Send image as image_url, image_base64 or multipart image. Returns a job id.

GET/api/v1/generations/:idFetch a generation’s status and, once ready, its result_image_url.

GET/api/v1/creditsReturn the current credit balance for the key.

Request parameters

Field	Type	Description
image_url	string	Public URL of the product photo. One of image_url / image_base64 / multipart is required.
image_base64	string	Base64-encoded image, as an alternative to image_url.
situation	string?	Free-text scene description. Optional — omit to use a house scene.
model	string?	Model id. Defaults to google-nano-banana.
aspect_ratio	string?	Target ratio (e.g. 4:5). Defaults to the input image ratio.
preferences	object?	Saved tone/style overrides applied to the scene.
webhook_url	string?	URL called with the result when the job finishes.

Models

google-nano-bananaDefault

Default. Instruction-edit model that keeps the product identical and rebuilds the scene. Output matches the input image ratio.

black-forest-labs/flux-1.1-pro

High-fidelity generation when you want a fresh composition. Honours the requested aspect_ratio.

flux-schnell

Lighter-weight generation for drafts and high-volume runs.

Webhooks

Pass a webhook_url and Embellify will POST the finished job to it — no polling required. Retries are attempted on non-2xx responses.

Ready to build?

Create a key and make your first call in under a minute.

Create an API key Start free