Model Context Protocol

MCP server

The whole APImage platform as 19 tools your agent can call directly. One endpoint, one bearer token, no SDK — Claude, Cursor, ChatGPT and 9 other clients connect in a single step.

Overview

A hosted, stateless proxy in front of the same REST API. Your key travels with each request, so one deployment serves every account and nothing of yours is stored on it.

Transport

Streamable HTTP

No stdio, no local process. Point a client at a URL.

Auth

Bearer API key

Your sk_ key on every call. There is no OAuth dance.

State

None

Each request builds a fresh server, so it scales behind a load balancer.

Credits, model access and plan limits are enforced server-side by the same code the dashboard uses. An agent calling generate_video on a free account gets the same 403 your own backend would.

Endpoint & auth

Two values are all any client needs: the server URL and an Authorization header.

POSThttps://mcp.apimage.org/mcp
Header
Authorization: Bearer sk_your_api_key

Where the key comes from

Generate one under Dashboard → API keys. It draws on the credits of the workspace it was created in, so give each team its own key if you want the spend separated.

Config files are not secret stores

Most clients keep MCP config in plain JSON inside your home directory. Treat that file the way you would an .env: keep it out of git, and rotate the key if it leaks.

GET /health on the same host is an unauthenticated liveness probe. GET and DELETE on /mcp return 405 — the server is POST-only because it holds no sessions.

Connect a client

Pick your client for exact steps. Anything that speaks remote Streamable HTTP works; stdio-only clients bridge through mcp-remote.

Where you work

Connect Claude Code

Anthropic's terminal coding agent

Claude Code docs
  1. 1

    Add the server

    Run this in your terminal. Drop -s user to scope it to the current project only, and replace the placeholder with your APImage API key:

    Terminal
    claude mcp add --transport http apimage https://mcp.apimage.org/mcp \
  --header "Authorization: Bearer sk_your_api_key" -s user
  2. 2

    Verify the connection

    Start Claude Code, run /mcp, and confirm apimage is connected. You'll see tools like generate_image, generate_video and check_credits.

    In Claude Code
    /mcp

Not listed? The generic shape below works in most clients that accept a remote MCP server.

{
  "mcpServers": {
    "apimage": {
      "url": "https://mcp.apimage.org/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_api_key"
      }
    }
  }
}

Tool reference

All 19 tools, with the arguments that matter and what each one costs. Your client lists the full JSON schema once connected.

Images

Generation and editing on FLUX 2 and GPT Image 2, plus the polling tools that go with them.

generate_image1–9 credits

Text to image. Reference images condition the result on existing artwork, a product or a character.

prompt, model, aspect_ratio, resolution, input_image_urls[], seed, visibility

edit_imageas a generation credits

Enhance, relight, colour grade, change camera angle, upscale or inpaint a masked region.

source_image_url, edit_tool, tool_option, prompt, mask_image

get_image_generationfree

Status and result URL for one image job. Polls the provider and finalises pending work.

id

list_image_generationsfree

Paginated image history, newest first, filterable by status.

status, limit, offset

Video

Seedance 2.0. Both generation tools are asynchronous and return a job id immediately.

generate_videometered credits

Text, image or video to video. Reference images carry brand assets into the shot.

prompt, mode, model, resolution, ratio, duration, input_image_url, input_video_url, reference_images[]

generate_lip_syncmetered credits

Talking avatar from a face image and a speech track. Audio caps at 30 seconds.

avatar_image_url, audio_url, audio_length_seconds, prompt, resolution

get_video_generationfree

Status and video URL for one job. Failed renders are already refunded.

id

list_video_generationsfree

Paginated video history, filterable by status and mode including lip-sync.

status, mode, limit, offset

Editing & analysis

The single-purpose operations an agent reaches for between generations.

remove_background2 credits

Transparent cutout as PNG or WebP.

image_url, output_format

replace_background3 credits

Swap the scene and relight the subject to match it.

image_url, background_prompt, foreground_prompt, light_source_direction, preserve_original_subject

analyze_image1 credits

Describe an image, extract its text, or answer a question about it.

image_url, prompt

enhance_promptfree

Rewrite a thin prompt into a detailed one for image or video.

prompt, target

Brand assets

The reusable library that keeps a campaign on-model across many generations.

list_brand_assetsfree

Browse characters, products, backgrounds or colour presets.

type, category, limit, offset

get_brand_assetfree

Fetch one asset by type and id.

type, id

create_brand_assetfree

Save an asset, usually from a URL a generation just produced.

type, name, image_url, category, attributes, tags, colors

update_brand_assetfree

Patch fields on an existing asset. Only what you send changes.

type, id, …fields

delete_brand_assetfree

Permanently remove an asset. There is no undo.

type, id

generate_brand_assetas a generation credits

Generate an image and save it to the library in one call.

type, name, prompt, model, aspect_ratio, category, attributes

Account

Cheap to call, and worth calling before a batch.

check_creditsfree

Credit balance, monthly usage against the quota, and subscription tier.

—

Every tool maps onto a documented REST endpoint. When you need the exact response shape or a parameter the tool does not expose, read the API reference.

Async generations

Video always runs in the background, and slow image jobs can too. The pattern is the same: take the id, poll the matching get_ tool.

What the agent does
1. generate_video({ prompt: "...", duration: 8, resolution: "1080p" })
   → { "id": "c41d7f8a-…", "status": "pending", "cost": 24 }

2. get_video_generation({ id: "c41d7f8a-…" })
   → { "status": "pending" }        # a render usually takes a few minutes

3. get_video_generation({ id: "c41d7f8a-…" })
   → { "status": "completed", "video_url": "https://cdn.apimage.org/…" }

Images usually finish inline

generate_image waits for the provider and normally returns a URL in one call. If it comes back pending, one get_image_generation call finalises it — that tool polls for up to a minute on the server side.

Tell your agent to wait, not to retry

Agents left to their own devices will re-call generate_video when a poll comes back pending, which bills a second render. Say so in your system prompt: poll the id, never regenerate.

Prompting agents

A few lines of standing instruction is the difference between an agent that burns credits and one that is genuinely useful.

Suggested system prompt fragment
When using the APImage tools:
- Call check_credits before a batch. It is free.
- Run enhance_prompt on thin user prompts first. Also free.
- Default to flux-2-pro at HD. Only use flux-2-max or 4K when
  the user asks for maximum quality — it costs up to 9x more.
- Video is asynchronous. After generate_video, poll
  get_video_generation with the returned id. Never regenerate.
- Reuse brand assets: list_brand_assets before inventing a new
  character or product, so output stays on-model.

Keep a campaign on-model

Save the approved character once with create_brand_asset, then pass its image URL as a reference on every later generation.

Cheap iteration, expensive finals

Draft on flux-2-klein-9b at HD for a credit each, then re-render only the chosen frame at 4K.

Product shots end to end

generate_image, remove_background, then replace_background — three tools, one conversation, no file juggling.

Close the loop

Feed a result back through analyze_image to check the render actually says what the brief asked for.

Errors & limits

Failures come back as MCP tool errors carrying the upstream HTTP status, so the agent can read them and adjust rather than stalling.

What the agent sees
APImage API error (HTTP 402): Insufficient credits: This costs 24 credits, but you have 11.
401 / 403

The key is missing, malformed, or the plan does not cover this tool. Video and premium models need a paid plan.

402

Out of credits. check_credits confirms the balance; top up or enable overage.

429

Rate limited, or too many videos rendering at once. Wait for one to finish.

502

The upstream model failed. Nothing was charged — the call is safe to retry.

Failed jobs are refunded

Credits are reserved when a generation starts and returned automatically if it fails, so a crashed render never leaves you short. Rate limits are inherited from the underlying REST endpoints — see rate limits.

Connect it in a minute

Generate a key, paste the endpoint into your client, and ask it to check your credit balance — that call is free and proves the connection.

Get an API keySee it in action