REST API

API reference

One key, nine endpoints. Generate and edit images, render video and lip sync, cut and replace backgrounds, read images back as text, and manage the brand assets your generations reuse.

Overview

Every endpoint lives under one base URL, speaks JSON, and is authenticated with the same API key.

POSThttps://app.apimage.org/api/v1/{endpoint}

Endpoint	Does	Credits
`/image-studio`	Generate & edit images (FLUX 2, GPT Image 2)	1–9
`/ai-image-generate`	OpenAI image models (GPT Image 2, DALL·E 3)	1–9
`/ai-video-generate`	Seedance & FLUX 3 video, lip sync	metered
`/generations`	Status and history for images and videos	free
`/ai-remove-background`	Transparent cutout	2
`/ai-replace-background`	Replace and relight the scene	3
`/ai-image-to-text`	Describe, OCR or answer questions	1
`/brand-assets`	Characters, products, backgrounds, palettes	free
`/usage`	Credit balance, quota and plan	free

Prefer to skip the plumbing?

The same capabilities are available as 20 tools over the MCP server, so Claude, Cursor or ChatGPT can call them directly without you writing a client.

Authentication

Send your API key as a bearer token on every request. Generate one under Dashboard → API keys.

Header

Authorization: Bearer sk_your_api_key

Accepted credentials

sk_…API key

The current format. Scoped to the workspace the key was created in, which is where credits are drawn from.

apimg_…legacy key

Still accepted, but responses carry a warning field. Rotate to an sk_ key.

eyJ…Supabase JWT

A signed-in user session, used by the dashboard itself. Pass x-workspace-id to target a specific workspace.

Do not ship keys to the browser

An ?api_key= query parameter is still honoured for legacy integrations, but it leaks through logs and referrers. Call the API from your server.

Credits & pricing

Credits are reserved before a job starts and settled when it finishes. Failed generations are refunded automatically, so a provider outage never costs you anything.

Model	HD	Full HD	4K
flux-2-klein-9b	1	1	2
flux-2-pro	1	2	4
flux-2-max	3	4	9
gpt-image-2	3	4	9

Reference images add a surcharge based on their megapixel count — doubled on flux-2-max and gpt-image-2, which bill input tokens at the premium rate. Video is metered per token and returns its exact cost in the response.

Check before you spend

GET /usage is free and returns the live balance. Call it once at boot rather than catching 402 in a retry loop.

Image Studio

The main image endpoint. One route covers generation, seven edit tools, prompt enhancement and status polling, selected by the action field.

POSThttps://app.apimage.org/api/v1/image-studio

action: generate

1–9 credits

The default when action is omitted. Pass reference images to condition the result on existing artwork, a product shot or a character.

promptstringrequired

What to generate.

modelstring

flux-2-pro (default), flux-2-klein-9b, flux-2-max or gpt-image-2.

aspect_ratiostring

1:1, 16:9, 9:16, 4:3, 3:4, 21:9 or 9:21. Defaults to 1:1.

resolutionstring

SD, HD, Full HD or 4K. Defaults to HD and drives the credit cost.

input_imagesstring[]

Up to 4 reference images as URLs or base64. Adds a megapixel surcharge.

width / heightnumber

Explicit pixel size, used only when aspect_ratio is absent.

seednumber

Fix for reproducible output.

safety_tolerancenumber

Provider moderation threshold. Defaults to 2.

visibilitystring

public or private. Public results can surface in the inspiration feed.

webhook_urlstring

Switches the call to async: returns immediately with status "processing" and an id, then POSTs the result here. Paid plans only.

webhook_secretstring

Signs the callback as X-APImage-Signature: sha256=<hmac>.

curl -X POST https://app.apimage.org/api/v1/image-studio \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cyberpunk city with flying cars and neon signs",
    "model": "flux-2-pro",
    "aspect_ratio": "16:9",
    "resolution": "Full HD"
  }'

Response 200

{
  "id": "8f3c1e02-4b6a-4c19-9d21-7a0f5be1c8d4",
  "status": "completed",
  "image_url": "https://cdn.apimage.org/...",
  "message": "Generation complete"
}

Slow jobs return pending

The endpoint waits up to 120 seconds. Past that it returns status: "pending" with the generation id. Poll it with action: "check_status" or GET /generations — the reservation is settled or refunded either way.

Or skip the wait with a callback

Pass webhook_url and the call returns as soon as the job is queued, with status: "processing" and the id — no 120-second hold. The finished image is POSTed to your URL. Use this from anywhere with a short request timeout. Requires a paid plan, since free-tier results are watermarked on the synchronous path.

action: edit

priced as a generation

source_imagestringrequired

URL or base64 of the image to transform.

edit_toolstringrequired

enhance, relight, color_grade, angle, upscale, inpaint or erase.

tool_optionstring

Preset for the chosen tool — a lighting style ("golden hour"), a grade ("cinematic") or a camera angle ("low angle").

promptstring

Extra instructions. Required in practice for inpaint; optional for erase, which defaults to filling the masked area from its surroundings.

mask_imagestring

Base64 mask. White marks the editable region. Required for inpaint and erase.

reference_imagestring

Inpaint only. Content to match inside the masked area.

webhook_urlstring

Same as on generate: returns immediately and POSTs the finished edit to your URL. Paid plans only.

Most tools are priced as a normal generation at the resolution they resolve to. erase is a flat 1 credit and inpaint without a reference_image is a flat 2, whatever the output size.

Request

{
  "action": "edit",
  "edit_tool": "relight",
  "tool_option": "golden hour",
  "source_image": "https://cdn.apimage.org/your-image.png"
}

action: enhance_prompt

free

Rewrites a thin prompt into a detailed one. Costs nothing, so run it on user input before spending credits on the generation.

Request & response

// POST
{ "action": "enhance_prompt", "prompt": "a dog on a beach" }

// 200
{
  "enhanced_prompt": "A golden retriever mid-stride across wet sand at low tide...",
  "original_prompt": "a dog on a beach"
}

action: check_status

free

Polls the provider for up to 60 seconds and finalises a pending generation — storing the result on success, refunding the reserved credits on failure.

Request

{ "action": "check_status", "generation_id": "8f3c1e02-4b6a-4c19-9d21-7a0f5be1c8d4" }

Background removal auto-routing

2 credits + input

Send an input_images entry with a prompt like "remove the background" and the router hands the job to the dedicated cutout engine instead of FLUX. Call /ai-remove-background directly when you want that behaviour guaranteed.

OpenAI images

A separate route for OpenAI's models. Reach for it when you need DALL·E 3, batches of up to four images per call, or the preset system.

POSThttps://app.apimage.org/api/v1/ai-image-generate

promptstringrequired

Required unless a preset is supplied.

modelstring

gpt-image-2 (default) or dall-e-3. Older ids such as gpt-image-1 resolve to gpt-image-2.

num_imagesnumber

1–4. Cost multiplies accordingly.

aspect_ratio + resolutionstring

Preferred sizing interface for gpt-image-2.

width / heightnumber

256–1792. Snapped to a valid size for gpt-image-2.

qualitystring

auto, low, medium, standard or high. DALL·E 3 at high quality costs 2 credits.

negative_promptstring

What to keep out of the frame.

seednumber

Reproducibility.

webhook_urlstring

Switches the call to async: returns immediately with a pending id and calls you back.

Response 200

{
  "success": true,
  "data": {
    "id": "2b91...",
    "status": "completed",
    "images": ["https://cdn.apimage.org/..."],
    "cost": 3
  }
}

Video & lip sync

Two model families — Seedance from BytePlus and FLUX 3 Video from Black Forest Labs — across five modes. Always asynchronous: the call returns an id and the exact credit cost, then you poll or take a webhook.

POSThttps://app.apimage.org/api/v1/ai-video-generate

Paid plans only

Video generation returns 403 on the free tier, and each account is capped at three in-flight jobs. A fourth returns 429 until one finishes.

Model	Resolution	Duration	Notes
seedance-2-0	480p, 720p, 1080p	4–15s	Default. The only model that does lip sync.
seedance-2-0-fast	480p, 720p	4–15s	Cheaper, no 1080p.
seedance-2-5	480p, 720p	4–30s	Newest. Longest clips, widest reference budget.
flux-3-video	hd, fhd	5–20s	Generates a synchronized audio track.
flux-3-video-draft	hd	5–20s	Cheap preview. Re-render later with draft-enhance.

The two families name resolutions differently

Seedance speaks 480p / 720p / 1080p. FLUX 3 speaks hd (= 720p) and fhd (= 1080p). Sending a resolution the chosen model does not support is a 400, so pick from the table above.

Common parameters

modestring

text-to-video (default), image-to-video, video-to-video, lip-sync or draft-enhance.

promptstring

Required for text-to-video, and required in every mode on FLUX 3. Recommended elsewhere.

modelstring

One of the five above. Defaults to seedance-2-0. Ignored for lip-sync (always Seedance 2.0) and draft-enhance (always flux-3-video).

resolutionstring

Per-model, per the table above. Defaults to 720p on Seedance and hd on FLUX 3.

ratiostring

Seedance: 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9. FLUX 3 adds auto (its default) and 2:1.

durationnumber

Output length in seconds, bounded per model. Ignored for lip-sync, which follows the audio, and for draft-enhance, which inherits the draft's.

generate_audioboolean

FLUX 3 only. Produces a synchronized audio track. Defaults to true — send false to opt out.

seednumber

Reproducibility.

safety_tolerancenumber

Provider moderation threshold, 0–4. Defaults to 2.

visibilitystring

public or private. Falls back to your account default.

webhook_urlstring

Called on completion or failure.

Mode-specific parameters

input_image_urlstring

First frame for image-to-video. The avatar image for lip-sync.

input_image_url_laststring

Optional last frame for image-to-video.

input_video_urlstring

Source clip for video-to-video.

input_video_lengthnumber

Length of that clip in seconds, 1–60. Required for video-to-video on Seedance, which bills the input's tokens; optional on FLUX 3, which prices per output second.

input_audio_urlstring

Speech track for lip-sync.

input_audio_lengthnumber

Audio length in seconds, 1–30. Sets the output duration for lip-sync.

source_generation_iduuid

Required for draft-enhance. The completed flux-3-video-draft generation to re-render.

Reference inputs — extra material the prompt can address

reference_imagesstring[]

Brand characters or products to carry into the shot. 9 on Seedance 2.0, 30 on 2.5, 10 on FLUX 3 (shared with the first/last frame slots).

reference_videosstring[]

Extra clips beyond input_video_url. 3 on Seedance 2.0, 10 on 2.5, 1 on FLUX 3.

reference_audiostring[]

3 on Seedance 2.0, 10 on 2.5. FLUX 3 takes no audio input at all and returns 400.

Over-sending is trimmed, not rejected

Reference lists are clamped to the model's budget server-side, so a client that sends 30 images to Seedance 2.0 gets the first 9 rather than an upstream error. Only reference_audio on FLUX 3 is a hard 400.

mode: lip-sync

3 credits / second

Drives a still avatar from a speech track. Always runs on Seedance 2.0 whatever model you send, and the audio length sets both the output duration and the price — a 20-second voiceover costs 60 credits.

mode: draft-enhance

priced as a full render

Re-renders a completed flux-3-video-draft clip on the full flux-3-video model. Prompt, mode, duration and ratio are inherited from the draft — only resolution is worth passing. Explore cheaply on drafts, then enhance the one take you want.

Request

{
  "mode": "draft-enhance",
  "source_generation_id": "c41d7f8a-9e2b-4f60-8a13-5d9c02b7e114",
  "resolution": "fhd"
}

curl -X POST https://app.apimage.org/api/v1/ai-video-generate \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "text-to-video",
    "model": "seedance-2-0",
    "prompt": "Slow dolly across a rain-soaked Tokyo alley at night",
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 8
  }'

Generations

Read-only status and history for everything you have created. Free, and the endpoint you poll while a video renders.

GEThttps://app.apimage.org/api/v1/generations

Query parameters

typestringrequired

image or video.

iduuid

Return one generation instead of a page.

statusstring

pending, processing, completed or failed.

modestring

Video only. Filters by generation mode, including lip-sync.

limitnumber

1–100. Defaults to 20.

offsetnumber

Pagination offset. Defaults to 0.

curl "https://app.apimage.org/api/v1/generations?type=video&id=c41d7f8a-9e2b-4f60-8a13-5d9c02b7e114" \
  -H "Authorization: Bearer sk_your_api_key"

Background tools

Two dedicated routes for the operations that carry a product shot: cut the subject out, or drop it into a new scene with matching light.

Remove background

2 credits

POSThttps://app.apimage.org/api/v1/ai-remove-background

image_urlstring

Source image. Required unless image_base64 is set.

image_base64string

Inline alternative to image_url. The data-URI prefix is optional.

output_formatstring

png (default) or webp.

webhook_urlstring

Optional completion callback.

Response 200

{
  "id": "6d20...",
  "status": "completed",
  "processed_image_url": "https://cdn.apimage.org/...",
  "original_size": 842113,
  "processed_size": 511204
}

Replace background

3 credits

POSThttps://app.apimage.org/api/v1/ai-replace-background

image_urlstringrequired

The subject image, or image_base64.

background_promptstringrequired

The scene to place it in. A background_image_url can be supplied instead.

foreground_promptstring

Describes the subject, which sharpens the matte.

negative_promptstring

What to keep out of the new scene.

light_source_directionstring

above, below, left or right.

preserve_original_subjectnumber

0–1. Higher keeps the subject closer to the original. Defaults to 0.6.

seednumber

Reproducibility.

Response 200

{
  "id": "a0f4...",
  "status": "completed",
  "url": "https://cdn.apimage.org/...",
  "format": "png",
  "credits_used": 3,
  "credits_remaining": 417
}

Image to text

Vision in reverse: describe an image, pull the text out of it, or ask a question about what it shows.

POSThttps://app.apimage.org/api/v1/ai-image-to-text

urlstringrequired

Image to analyse. A multipart file upload is also accepted.

promptstring

What you want back — "Extract all text" or "Which products are shown?". Defaults to a detailed description.

webhook_urlstring

Optional completion callback.

Response 200

{
  "id": "71ae...",
  "status": "completed",
  "description": "A matte-black espresso machine on a walnut counter...",
  "tokens_used": 412,
  "created_at": "2026-07-25T09:20:03.884Z"
}

Brand assets

The reusable library behind consistent output: characters, products, backgrounds and colour presets. Full CRUD on one route, free to call.

GEThttps://app.apimage.org/api/v1/brand-assets?type=character

POSThttps://app.apimage.org/api/v1/brand-assets

PATCHhttps://app.apimage.org/api/v1/brand-assets

DELETEhttps://app.apimage.org/api/v1/brand-assets?type=product&id={uuid}

typestringrequired

character, product, background or color_preset. Required on every method.

iduuid

Targets a single asset. Required for PATCH and DELETE.

namestring

Required when creating.

image_urlstring

Characters, products and backgrounds. Usually a generated image you are keeping.

sourcestring

generated or uploaded.

categorystring

Groups products, backgrounds and presets. Also filters GET.

attributesobject

Free-form traits — gender, age_range, hair_color, clothing_style, custom_details.

colorsstring[]

Hex values. Required when creating a color_preset.

tagsstring[]

Backgrounds and colour presets.

limit / offsetnumber

Pagination on GET. Limit defaults to 50, max 100.

Create a character

curl -X POST https://app.apimage.org/api/v1/brand-assets \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "character",
    "name": "Mara, brand spokesperson",
    "image_url": "https://cdn.apimage.org/generated/mara.png",
    "source": "generated",
    "attributes": { "age_range": "30-35", "clothing_style": "minimal workwear" }
  }'

Usage & credits

One free call for balance, quota and plan. Useful as a key-validity check on startup.

GEThttps://app.apimage.org/api/v1/usage

Response 200

{
  "monthly_usage": 1284,
  "monthly_limit": 5000,
  "remaining": 3716,
  "credits": 417,
  "subscription_tier": "pro",
  "email": "you@studio.com",
  "name": "Your Name"
}

Webhooks

Long jobs can call you instead of you polling them. Pass webhook_url on image studio, video, OpenAI image, background and analysis requests.

The callback is a POST carrying the same body the polling endpoint would have returned, plus a completion timestamp. Treat delivery as at-least-once and key your handler on the generation id.

Callback body

{
  "id": "c41d7f8a-9e2b-4f60-8a13-5d9c02b7e114",
  "status": "completed",
  "video_url": "https://cdn.apimage.org/...",
  "cost_charged": 24,
  "completed_at": "2026-07-25T09:18:11.402Z"
}

Failures call back too

A failed job posts status: "failed" with an error message. The reserved credits are already back on your balance by then.

Rate limits

Per-minute ceilings, returned on every response as X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Endpoint	Requests / min
/generations, /brand-assets	120
/ai-image-generate	60
/ai-video-generate	30
/ai-remove-background, /ai-replace-background	30

Video also enforces a concurrency cap on in-flight jobs, which returns 429 with a message naming the limit. Back off and retry once a render finishes.

Errors

Every failure is JSON with an error label and a human-readable details string.

Error shape

{
  "error": "Insufficient credits",
  "details": "This costs 24 credits, but you have 11.",
  "status": 402
}

400

Bad request. A parameter is missing or outside its allowed range.

401

Authentication failed. No key, or the key is malformed.

402

Insufficient credits. Top up, or enable overage billing.

403

Forbidden. Key not recognised, or the plan does not include this feature.

404

Not found. The id does not exist, or belongs to another account.

429

Rate limited. Too many requests, or too many videos in flight.

502

Provider error. The upstream model failed. Credits were not charged.

500

Internal error. Unexpected failure. Any reservation is rolled back.

Ready to make the first call?

Create a key in the dashboard, then start with GET /usage to confirm it works before spending a credit.

Get an API key Use the MCP server instead