# VidMage developer integration

> Canonical, machine-readable setup guide for AI coding agents. This document is rendered by the server from the same deployment configuration as VidMage REST discovery, OpenAPI, and MCP tools. Do not scrape the JavaScript application or search the web for endpoint details.

Fetch this document as text over HTTP. If a browser refuses direct ".md" navigation, use the Agent's HTTP client or `curl -fsSL` instead of scraping the rendered page.

## If the user only gave you a Developers page URL

1. Read this Markdown document and choose MCP for an MCP-capable AI client, or REST for application code.
2. Do not attempt a paid generation as a connection test.
3. VidMage access requires an active subscription and a dedicated API key from https://vidmage.ai/developers/console. The user must copy the generated configuration directly into the Codex user-level configuration; never request or expose the key in chat, logs, shell history, or source control.
4. For MCP, change only the host AI client's user-level/global configuration. Preserve all other servers and settings; do not create MCP configuration in the user's project.
5. After the client has loaded the server, call the real VidMage **list_capabilities** MCP tool with a small limit. Editing a configuration file or reaching the endpoint from a helper script is not a successful integration. Report success only after this authenticated, read-only call succeeds.

Expected human handoffs are limited to creating/copying the secret and restarting the host client. The static Authorization header persists in the user-level configuration and is reloaded for each new task and after a full Codex restart. Verification must happen in a new task because an already-open task does not acquire newly configured tools.

There are two independent readiness gates. Deployment operators must first confirm the authenticated Developers MySQL readiness endpoint returns `ready: true`. The user must then confirm `codex mcp get vidmage` still finds the direct user-level server after a full restart. Only a successful **list_capabilities** call in a new task proves both gates and the actual MCP tool mount.

## Authoritative endpoints

- Human documentation: https://vidmage.ai/developers/docs
- AI-agent guide: https://vidmage.ai/developers.md
- Developer Console and credentials: https://vidmage.ai/developers/console
- REST discovery root: https://vidmage.ai/api/v1
- Capability catalog: https://vidmage.ai/api/v1/capabilities
- OpenAPI 3.1: https://vidmage.ai/api/v1/openapi.json
- MCP Streamable HTTP: https://vidmage.ai/api/mcp

## Recommended MCP setup

Create a dedicated API key in https://vidmage.ai/developers/console. The key is shown once. Copy the complete generated Codex configuration directly from that creation dialog into the user-level `~/.codex/config.toml`; never send the key or completed configuration through chat, shell history, logs, or source control.

The generated entry has this shape:

~~~toml
# ~/.codex/config.toml
# Direct, persistent user-level MCP registration; this is not a plugin install.
# Replace any existing [mcp_servers.vidmage] table; do not append a duplicate.
[mcp_servers.vidmage]
url = "https://vidmage.ai/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }
enabled = true
required = true
startup_timeout_sec = 30
tool_timeout_sec = 120
# Save this file, then confirm persistence with: codex mcp get vidmage
# Restrict the user-level file after saving: chmod 600 ~/.codex/config.toml
# Diagnose this direct server from VidMage startup errors; a remote Plugins catalog 401 is unrelated.
# Fully restart Codex, create a new task, and call list_capabilities.
~~~

Replace the placeholder only in the local file, or preferably copy the ready-to-use configuration shown immediately after key creation. Replace any existing `[mcp_servers.vidmage]` table instead of appending a duplicate, and preserve every unrelated setting and server in the file. This is a direct, persistent user-level MCP registration—not a plugin installation. Seeing a VidMage card or preview in Plugins does not prove this server was installed or persisted.

After saving, run `codex mcp get vidmage`. It must show the configured URL and enabled state without printing the secret. Fully quit Codex, repeat that check in the new process, then open a new task and call **list_capabilities** with a small limit.

### Other MCP clients

The same API key can authenticate REST, Claude Code, Cursor, and other manual MCP clients. API keys are shown only once. Copy a key directly into the target client; do not send it to an Agent. Claude Code reads the key interactively so it is not written into shell history.

### Claude Code (user scope)

~~~sh
printf 'VidMage API key: ' >&2
IFS= read -r -s VIDMAGE_API_KEY
printf '\n' >&2
export VIDMAGE_API_KEY
claude mcp add --transport http vidmage --scope user "https://vidmage.ai/api/mcp" \
  --header "Authorization: Bearer ${VIDMAGE_API_KEY}"
unset VIDMAGE_API_KEY
~~~

### Cursor (global ~/.cursor/mcp.json)

~~~json
{
  "mcpServers": {
    "vidmage": {
      "url": "https://vidmage.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
~~~

After applying the configuration, reload or restart if the host client requires it. For Codex, a full restart and a new task are mandatory for validation. Then call **list_capabilities** with a small limit. A successful catalog response proves authenticated tool access and consumes no credits.

### Codex tool validation and troubleshooting

- A working Codex task exposes the compact VidMage surface: **list_capabilities**, **describe_capability**, **upload_files**, **submit_task**, **get_task_result**, **select_faces**, and **get_recent_tasks**. Fully qualified tool names may be displayed with an `mcp__vidmage__` prefix.
- VidMage uses a direct user-level `[mcp_servers.vidmage]` entry with a static API-key Authorization header. It is not installed by merely seeing or selecting a VidMage plugin card. Do not run `codex mcp login`, start browser linking, or treat an installed hosted plugin as proof that this local entry is configured.
- When Codex startup output contains multiple warnings, diagnose this direct server from `required MCP servers failed to initialize: vidmage` and its following VidMage error. A separate 401 from the remote Plugins catalog is unrelated to this user-level registration and is not fixed by `codex mcp login vidmage`.
- The generated entry sets `required = true`. If VidMage cannot authenticate or initialize, Codex must surface startup/resume failure instead of silently creating a task without VidMage tools. Fix the configuration or service reachability; do not weaken this to `required = false` merely to hide the failure.
- A standalone **face_swap** tool is not expected in the default compact tool surface. For a face swap, search for `face swap` with **list_capabilities**, load the schema with **describe_capability**, prepare all local inputs in one **upload_files** call, run its upload commands in parallel, submit exactly once with **submit_task**, and poll the returned task with **get_task_result**. Detection is part of that task; call **select_faces** only if it returns `NEEDS_INPUT`.
- If a new task cannot see any `mcp__vidmage__` tools, stop and report that this task has no mounted VidMage tool. Confirm that the real Key—not `YOUR_API_KEY`—is in the user-level file, fully restart Codex, and create another new task. Do not write a Python helper, call JSON-RPC/REST directly, or use another image tool as a fallback while claiming MCP success.
- If the endpoint returns HTTP 503 with `CREDENTIAL_STORAGE_UNAVAILABLE`, the key has not been classified as invalid and no tool or generation task ran. Preserve the key and configuration, honor `Retry-After`, and retry once. If it persists, stop, report the non-secret `requestId` to support, and ask a deployment operator to restore Developers MySQL readiness. Do not rotate the key, run MCP login, or resubmit generation.
- If initialize returns HTTP 401 with `API_KEY_INVALID_OR_REVOKED`, Codex did send an Authorization credential, but that key is invalid, revoked, or absent from the current Developers store. Create a new key in the Developer Console, replace only the Authorization value in the existing user-level entry, fully restart Codex, and verify in a new task. `API_KEY_INVALID_CREDENTIAL` means the stored credential cannot be decrypted and also requires a new key in the target client. `AUTHENTICATION_REQUIRED` instead means no credential reached VidMage; `AUTHORIZATION_HEADER_INVALID` means the header was present but malformed.
- A direct script can prove the endpoint, API key, and generation backend work, but it does not prove that Codex mounted the MCP tools from its persistent user-level configuration.

## MCP operating rules

- Every MCP method and REST Developer API endpoint requires a subscription-backed API key. API keys have read and generation permissions. A short-lived upload URL can only be issued after authentication; possession of that scoped URL authorizes only its declared one-file PUT until expiry.
- Confirmed failed tasks are refunded automatically only when the refund outcome is known. An unknown provider, billing, or refund outcome remains pending manual reconciliation. Do not resubmit the task or attempt another refund while the outcome is unknown.
- For **SUBMISSION_OUTCOME_UNKNOWN**, **BILLING_OUTCOME_UNKNOWN**, or **REFUND_OUTCOME_UNKNOWN**, follow the returned `recovery` exactly. `GET_RECENT_TASKS` means call **get_recent_tasks**; `QUERY_TASK_ID_OR_CONTACT_SUPPORT` means query the same `taskId` or contact support; `CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID` means contact support with the original `idempotencyKey` and returned `businessId`. Never create a new `idempotencyKey`, resubmit, or attempt another refund.
- **BILLING_INVARIANT_FAILED** means the provider accepted the task but VidMage could not verify its credit charge. Do not retry, rotate the API key, change the original `Idempotency-Key`, or resubmit. Contact support with `taskId` when present, `capability`, and the original `Idempotency-Key`; for REST, also include `X-Request-Id`.
- Call **list_models** when the model slug is unknown and **estimate_model_credits** before a paid generation. Both are read-only and consume no credits.
- When the user requests a character or figurine without naming an IP, make the prompt explicitly describe an original non-branded character with no logos and no resemblance to existing copyrighted superheroes. This reduces model bias toward familiar franchises. If the user explicitly names a character or brand, preserve that request rather than silently applying this default. VidMage passes the Agent's prompt through; the server does not rewrite it.
- Capabilities are discovered dynamically rather than exposed as one tool per capability. Translate user intent from any language into a concise English phrase and treat **category** as the requested output artifact: a 3D-style rendered picture belongs to `image`; use `3d` only when the user wants an actual GLB/3D model file. If the capability is already known, skip discovery. Otherwise call **list_capabilities**, then **describe_capability** only for the selected slug. Submit once with **submit_task**, then call **get_task_result** once per poll and wait at least its returned `retryAfterMs`; the server never holds a long poll or sleeps on behalf of the Agent.
- If a submit response is lost, call **get_recent_tasks** to recover the task ID before considering any retry. Only a transport retry of the same submission may reuse its original **idempotencyKey**; never create a new key merely because the response or polling connection was interrupted.
- For one to five local files, call **upload_files** once with the exact target **capability** and one descriptor per destination **parameter**. Run all returned **uploadCommand** values in parallel, then pass each **fileUrl** only to its declared parameter. Upload preparation validates type and size; submission verifies the uploaded bytes, measures real media duration, and checks subscription and credits before billing. Do not add a separate duration or credit preflight, generate an upload script, use browser automation, or encode video as Base64.
- Face detection runs inside the submitted task. Omit face indexes when the user has not selected them. Exactly one detected target/reference face is selected automatically. If **get_task_result** returns `NEEDS_INPUT`, stop polling, show every native cropped preview with its stable index, ask the user, then call **select_faces** once and continue polling the same task. Never infer indexes from layout order or submit a replacement task. Video/GIF target previews are returned after the same forced R/B channel correction as the website; do not display their raw source URLs.
- For a user-requested result, pass an absolute writable **localPath** to **get_task_result**. When it completes, run **artifact.downloadCommand** exactly once, verify **artifact.clientLocalPath** exists, and embed that local file in the final user response. Native MCP image/audio/file content is still returned when small enough, but a host may not surface it automatically. Downloading materializes the same task result and consumes no credits; never submit a replacement task because download or preview failed.
- Generation consumes subscription credits. Get explicit user intent before running a paid generation when the request was only to configure or verify the integration.

### End-to-end image example

For the explicit request **"Use VidMage MCP to generate an image: dog and cat play with ball"**, use this exact control flow:

1. `list_capabilities { "category": "image", "search": "image generation" }` (skip this when the capability is already known).
2. `describe_capability { "capability": "<exact returned slug>" }` only if its input schema is not already known.
3. `submit_task { "capability": "<same slug>", "input": { "prompt": "A dog and a cat playing with a ball" }, "idempotencyKey": "dog-cat-ball-<fresh-unique-suffix>" }` exactly once.
4. Call `get_task_result` with the same capability, task ID, and an absolute writable `localPath`; while running, wait at least `retryAfterMs` before the next call. On completion, run `artifact.downloadCommand` exactly once, verify `artifact.clientLocalPath` exists, and embed that absolute local path as an image.
5. If the submission response was lost, call `get_recent_tasks` before considering any retry. Reuse the same idempotency key only for a transport retry, and never create a second paid task merely because polling was interrupted.

## REST integration

Import https://vidmage.ai/api/v1/openapi.json instead of inferring request fields from the website. Authenticate every protected request with:

~~~http
Authorization: Bearer YOUR_API_KEY
~~~

Use **GET /api/v1/capabilities** for live discovery. All generation tasks are asynchronous: call **POST /api/v1/{capability}/submit** exactly once with a stable **Idempotency-Key**, retain the returned task ID, and poll **POST /api/v1/{capability}/query** for that same task until it reaches a terminal state.

REST clients may use **POST /api/v1/face-analysis** to inspect target indexes before submitting explicit face indexes. MCP clients should use the integrated task flow above; `faceAnalysisId` is not part of the capability submission contract.

## Enabled capability slugs (59)

- image: face-swap, multiple-face-swap, text-to-image, image-to-image, ai-girl-generator, ai-hairstyle-changer, clothes-changer, object-remover, image-watermark-remover, image-upscaler, gpt-image-2-image-to-image, gif-face-swap, midjourney-ai-image-generator, grok-ai-image-generator, nano-banana-ai-image-generator, gpt-image-generator, seedream-ai-image-generator, z-image-ai-model, wan-image-generator, qwen-image-generator, gpt-image-2-generator
- video: video-face-swap, multiple-face-swap-video, text-to-video, image-to-video, video-to-video, video-extender, video-to-anime-converter, video-background-remover, watermark-removal, sora-link-watermark-removal, sora2, photo-dance, motion-control, ai-talking-photo, lip-sync, subtitle-generator, video-upscaler, kling-ai-video-generator, pixverse-ai-video-generator, hailuo-ai-video-generator, grok-video-generator, sora-2-ai-video-generator, wan-ai-video-generator, seedance-2-0-ai-video-generator, seedance-ai-video-generator, midjourney-video-generator, vidu-ai-video-generator, veo-3-1-ai-video-generator, kling-3-0-ai-video-generator, skyreels-ai-video-generator, happyhorse-ai-model, runway-ai-video-generator
- audio: voice-clone, voice-design, text-to-music
- 3d: ai-image-to-3d-model, ai-four-view-to-3d-model, ai-text-to-3d-model

The live catalog and parameter schemas at https://vidmage.ai/api/v1/capabilities and https://vidmage.ai/api/v1/openapi.json are authoritative if this list changes.