iArt API and MCP server

Overview

REST base URL https://app.iart.ai/api/v1. MCP server https://app.iart.ai/api/mcp. Requests and answers are JSON. The flow is always the same: create a video, then read it every 30–60 seconds until its status is done, failed or stopped. A finished video can be revised; each revision is made, and charged, again.

Authentication

Create a key on the API page in iArt (account menu → API); it is shown once. Send it as Authorization: Bearer YOUR_API_KEY or x-api-key: YOUR_API_KEY. An account can hold 10 keys; revoke one any time. A key keeps working for reading your videos if your plan lapses, but creating, revising and uploading need an active Pro, Ultra or Max plan.

MCP server

Streamable HTTP, stateless, no OAuth: the key goes in a header. Listing the tools needs no key; calling one does. The tools are create_video, get_video, revise_video, stop_video and upload_file, with the same fields as the REST calls below. A refusal comes back as a tool error whose text is the error body (see Errors), so your agent can read it. Setup for Claude Code, Codex, Cursor and VS Code is on the MCP page.

claude mcp add --transport http iart https://app.iart.ai/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

Create a video

POST/api/v1/videos· MCP tool create_video

Starts a video and answers at once (201) with its id and status writing. Refused before anything starts when your plan, credits, videos-at-once limit, resolution or files don’t allow it.

curl -X POST https://app.iart.ai/api/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 15-second launch video for Acme Notes. Scene 1: logo.png on #0f172a. Scene 2: the headline \"Notes that write themselves\" types on in white. Voice-over: …",
    "aspect_ratio": "16:9",
    "model": "sonnet-5.5",
    "resolution": "1080p",
    "files": ["https://acme.example/brand/logo.png"]
  }'

{
  "id": "7bac47f8-c9e4-4c80-862f-baf7a9ecdb95",
  "status": "writing",
  "progress": 0,
  "scenes": 0,
  "error": null,
  "mp4_url": null,
  "share_url": null,
  "edit_url": null,
  "estimated_cost": 1.11
}

Get a video

GET/api/v1/videos/{id}· MCP tool get_video

The video’s state. Read it every 30–60 seconds; 300 reads a minute per key are allowed. A video whose run has ended without finishing is marked failed when read.

curl https://app.iart.ai/api/v1/videos/VIDEO_ID -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "7bac47f8-c9e4-4c80-862f-baf7a9ecdb95",
  "status": "done",
  "progress": 1,
  "scenes": 2,
  "error": null,
  "mp4_url": "https://…/video.mp4",
  "share_url": "https://app.iart.ai/share/…",
  "edit_url": "https://app.iart.ai/p/…"
}

Revise or retry

POST/api/v1/videos/{id}/revise· MCP tool revise_video

For a done video, instructions (required) say what to change, and files can add up to 10 more. For a failed or stopped video, send neither: it is retried as it was, from where it stopped. It is made, and charged, again, at the resolution it was made at.

curl -X POST https://app.iart.ai/api/v1/videos/VIDEO_ID/revise \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"instructions": "Make the logo bigger and use photo.jpg in scene 2", "files": ["https://acme.example/photo.jpg"]}'

Stop a video

POST/api/v1/videos/{id}/stop· MCP tool stop_video

Stops a video being made, for example when the brief was wrong. What it used so far is charged; retry it later with revise. Stopping a video that isn’t being made changes nothing and answers its state.

curl -X POST https://app.iart.ai/api/v1/videos/VIDEO_ID/stop -H "Authorization: Bearer YOUR_API_KEY"

Files

A video can use your logo, screenshots, product photos, a voice recording or a PDF. Put up to 10 in files, and name each in the brief with what to do with it. A file is either:

• A public https URL, fetched when the video starts, up to the limits below. It must be reachable without signing in, on the standard port, and may redirect up to 3 times; all of a request’s URLs must download within 2 minutes. Private and local addresses are never fetched.
• An upload of a file on your computer, up to 4 MB. Over REST, send the file as the body; over MCP, upload_file gives your agent a link to send it to with curl, valid for 15 minutes, no key needed. Either way the answer’s file_url goes in files; uploads are kept 7 days.

curl -X POST "https://app.iart.ai/api/v1/files?name=logo.png" \
  -H "Authorization: Bearer YOUR_API_KEY" --data-binary @logo.png

# → 201 {"file_url": "https://…/logo.png", "name": "logo.png", "size": 48213}

# upload_file {"name": "logo.png"} answers with a link valid for 15 minutes:
curl -sS -T logo.png 'https://app.iart.ai/api/v1/files?token=…'

# → 201 {"file_url": "https://…/logo.png", …}; pass file_url in files

Every file is checked before it is used. Its content must be the type its name says (a renamed file is refused), and it is served as that type. An SVG must be a plain image: no scripts, event handlers, links to other files or embedded content; export it as a plain SVG, or as a PNG. Two files can’t share a name. Each account can add 200 files or 1 GB in any 24 hours.

The video object

Every call that concerns a video answers with it.

Errors

An error is an HTTP status with a JSON body: error (what happened, in words you can show), code when there is one, and upgrade_url on 402. Over MCP the same body is the tool error’s text.

{
  "error": "Your plan makes videos up to 1080p. Use a lower resolution or upgrade.",
  "code": "RESOLUTION_NOT_ALLOWED"
}

Limits

Videos at once count every video your account is making, here and with Batch in the app. Per key: 300 reads and 60 creates, revisions, stops or uploads a minute. Per account: 10 keys; 200 files or 1 GB of files in any 24 hours. A prompt or instructions: up to 8,000 characters.

Pricing

Videos use your credits at the same prices as the app, charged as they are used: the model’s tokens, plus $0.09 per rendered scene and $0.045 to combine them, at any resolution; voice-over as in the app. A video is refused up front when your credits can’t cover it on top of the videos you have in progress.

Prices include the service fee. See plans.