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 2.0 video and 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 19 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, six 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.

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.

action: edit

priced as a generation

source_imagestringrequired

URL or base64 of the image to transform.

edit_toolstringrequired

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

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.

mask_imagestring

Base64 mask for inpaint. White marks the editable region.

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

Seedance 2.0 in four 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 Upgrade required on the free tier, and each account is capped at a small number of in-flight jobs.

Common parameters

modestring

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

promptstring

Required for text-to-video, recommended everywhere else.

modelstring

seedance-2-0 (default, up to 1080p) or seedance-2-0-fast (cheaper, up to 720p).

resolutionstring

480p, 720p (default) or 1080p.

ratiostring

16:9 (default), 9:16, 1:1, 4:3, 3:4 or 21:9.

durationnumber

Output length in seconds, 4–15. Ignored for lip sync, which follows the audio.

reference_imagesstring[]

Up to 4 image URLs — brand characters or products to carry into the shot.

seednumber

Reproducibility.

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

Reference clip for video-to-video.

input_video_lengthnumber

Length of that clip in seconds, 1–60. Required for video-to-video.

input_audio_urlstring

Speech track for lip-sync.

input_audio_lengthnumber

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

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",
    "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 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