MCP tool reference

create_video

Create a project and start a video from a brief. Returns immediately with a run ID. Wait poll_after_seconds, then call get_run until the run ends. Spends the team's existing credits, within the limits approved for this key or connection.

Required permission: videos:write

The creator may ask a question instead of producing a film. A completed run does not guarantee a new video: read reply and new_films. Every project can also be opened in the Ghostmotion editor.

Inputs

Example request

{
  "name": "create_video",
  "arguments": {
    "request_id": "launch-video-001",
    "brief": "Make a 20-second launch video for a collaborative design app. Show the problem, introduce the app, and end with an invitation to try it.",
    "duration_seconds": 20,
    "aspect_ratio": "16:9"
  }
}

Result · structuredContent

{
  "project_id": "project-id",
  "run_id": "run-id",
  "project_url": "https://app.ghostmotion.ai/p/project-id",
  "status": "accepted",
  "poll_after_seconds": 15
}

Errors

unauthorized, permission_denied, not_found, invalid_request, insufficient_credits, allowance_exhausted, cap_too_low, idempotency_conflict, request_in_progress, upload_not_ready, character_not_ready, rate_limited, internal_error, temporarily_unavailable.

send_message

Send an edit, an answer or more direction to a project's creator. Only the project's original author can direct it. Starts a new run and uses workspace credits.

Required permission: videos:write

Wait for the current run to finish, or stop it first. A retry uses the same request ID and input. A new edit needs a new request ID. Poll the newly returned run ID for the result.

Inputs

Example request

{
  "name": "send_message",
  "arguments": {
    "project_id": "project-id",
    "request_id": "launch-edit-001",
    "message": "Make the opening faster and add captions."
  }
}

Result · structuredContent

{
  "project_id": "project-id",
  "run_id": "edit-run-id",
  "project_url": "https://app.ghostmotion.ai/p/project-id",
  "status": "accepted",
  "poll_after_seconds": 15
}

Errors

unauthorized, permission_denied, not_found, invalid_request, project_busy, insufficient_credits, allowance_exhausted, cap_too_low, idempotency_conflict, request_in_progress, upload_not_ready, character_not_ready, rate_limited, internal_error, temporarily_unavailable.

get_run

Get a run's progress, creator reply, newly published videos, project URL and credit usage. While running, wait poll_after_seconds before checking again.

Required permission: projects:read

Terminal states are completed, failed, cancelled and interrupted. new_films only contains films published by this run. Links expire after one hour; call get_run again for fresh links. Downloads recheck the issuing key's validity and project access. MCP does not automatically wake an assistant when work finishes.

Inputs

Example request

{
  "name": "get_run",
  "arguments": {
    "run_id": "run-id"
  }
}

Result · structuredContent

{
  "run_id": "run-id",
  "project_id": "project-id",
  "project_url": "https://app.ghostmotion.ai/p/project-id",
  "status": "completed",
  "started_at": "2026-01-01T12:00:00.000Z",
  "ended_at": "2026-01-01T12:02:00.000Z",
  "reply": "Your video is ready.",
  "message_so_far": null,
  "new_films": [
    {
      "version": "v001",
      "variation": "a",
      "url": "https://app.ghostmotion.ai/api/v1/media/example-token",
      "expires_at": "2026-01-01T13:02:00.000Z"
    }
  ],
  "credits": {
    "charged": 2.5,
    "reserved": 0
  }
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.

list_projects

List accessible workspace projects, newest first, with authorship, edit permission and the latest run.

Required permission: projects:read

Pass next_cursor unchanged as cursor to get another page. A null next_cursor means there are no more pages. Visibility does not grant edit access: check can_direct. Legacy projects without a workspace assignment are excluded until migrated.

Inputs

Example request

{
  "name": "list_projects",
  "arguments": {
    "limit": 20
  }
}

Result · structuredContent

{
  "projects": [
    {
      "project_id": "project-id",
      "name": "App launch",
      "project_url": "https://app.ghostmotion.ai/p/project-id",
      "created_by": "Alex",
      "you_created_it": true,
      "can_direct": true,
      "origin": "API key Launch pipeline",
      "updated_at": "2026-01-01T12:02:00.000Z",
      "latest_run": {
        "run_id": "run-id",
        "status": "completed"
      }
    }
  ],
  "next_cursor": null
}

Errors

unauthorized, permission_denied, not_found, invalid_request, rate_limited, internal_error, temporarily_unavailable.

list_characters

List the team's characters (AI characters, illustrated characters and digital twins) and whether each is ready to cast in a video.

Required permission: projects:read

Cast a ready character with cast: [{ character_id }] in create_video or send_message. A character still being made has status drafting; one whose run ended without a version has status unmade (ask for changes with send_message on its project_id). Digital twins of real people are created in Ghostmotion, where the person gives consent.

Inputs

No query parameters required.

Example request

{
  "name": "list_characters",
  "arguments": {}
}

Result · structuredContent

{
  "characters": [
    {
      "character_id": "character-id",
      "name": "Maya",
      "kind": "ai_character",
      "status": "ready",
      "ready": true,
      "version": 1,
      "character_url": "https://app.ghostmotion.ai/characters/character-id"
    }
  ]
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.

create_character

Create an AI character (a photorealistic person who is not a real individual) or an illustrated character from a description and optional reference images. Returns at once with a run ID: poll get_run until it ends. When get_run's character.ready is true, cast it in videos. Uses workspace credits.

Required permission: videos:write

Describe their look, age, style and personality, and a voice if they should speak. Reference images guide the look. Follow-up changes go to send_message with the character_id as project_id. Digital twins of real people cannot be created here: they are made in Ghostmotion, where the person gives consent.

Inputs

Example request

{
  "name": "create_character",
  "arguments": {
    "request_id": "maya-001",
    "name": "Maya",
    "kind": "ai_character",
    "description": "A 28-year-old product designer with short curly black hair, warm and direct. A calm, friendly voice."
  }
}

Result · structuredContent

{
  "project_id": "character-id",
  "run_id": "run-id",
  "project_url": "https://app.ghostmotion.ai/characters/character-id",
  "status": "accepted",
  "poll_after_seconds": 15,
  "character_id": "character-id"
}

Errors

unauthorized, permission_denied, not_found, invalid_request, insufficient_credits, allowance_exhausted, idempotency_conflict, request_in_progress, upload_not_ready, temporarily_unavailable, rate_limited, internal_error, temporarily_unavailable.

stop_run

Request cancellation of one run on a project you created. Safe to repeat: it never stops a newer run.

Required permission: videos:write

stopping means cancellation was requested, not that it has finished. Poll get_run until it ends. Saved work remains, and work already done may still be charged. An already-ended run returns its terminal status.

Inputs

Example request

{
  "name": "stop_run",
  "arguments": {
    "run_id": "run-id"
  }
}

Result · structuredContent

{
  "run_id": "run-id",
  "status": "stopping",
  "poll_after_seconds": 5
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.

prepare_reference_upload

Create a one-hour upload URL for an image, document, video, audio file, font, GLB or STL model. PUT raw file bytes to upload_url using the returned headers, then include upload_id in a creation or edit request.

Required permission: videos:write

Chat attachments are not visible to Ghostmotion until uploaded. There is no file-size cap (max_bytes is null); respect expires_at. upload_url is a private Google Cloud Storage resumable session: the file goes straight to storage, whatever its size, and storage answers the PUT (200 or 201 once it has the whole file). One PUT of the whole file works; so do Content-Range chunks with resume (a 308 reports the persisted Range). The upload is verified when a creation or edit first uses it; complete_reference_upload verifies it earlier and answers { upload_id, status: "ready", bytes }. size_bytes is optional and advisory. sha256 is optional and verified. upload_mode is accepted for compatibility and changes nothing. Models are inspected when attaching them to a real project, before starting the creator. Treat upload_url as a secret. Prepare a fresh upload if it expires or was consumed by another request. Preparing again creates another upload; this operation has no request_id.

Inputs

Example request

{
  "name": "prepare_reference_upload",
  "arguments": {
    "filename": "logo.png",
    "content_type": "image/png"
  }
}

Result · structuredContent

{
  "upload_id": "upload-id",
  "upload_url": "https://storage.googleapis.com/upload/storage/v1/b/example-uploads-quarantine/o?uploadType=resumable&name=public%2Fupload-id%2Fsource&upload_id=example-session",
  "method": "PUT",
  "headers": {
    "content-type": "image/png"
  },
  "max_bytes": null,
  "expires_at": "2026-01-01T13:00:00.000Z",
  "upload_mode": "resumable",
  "chunk_bytes": 8388608,
  "complete_url": "https://app.ghostmotion.ai/api/v1/reference-uploads/upload-id/complete",
  "complete_by": "2026-01-01T13:00:00.000Z"
}

Errors

unauthorized, permission_denied, not_found, invalid_request, rate_limited, internal_error, temporarily_unavailable.

complete_reference_upload

Optional: verify an uploaded reference before using it (create_video and send_message run the same verification on first use). Rechecks the original issuing key, ownership and workspace permissions, and validates size, type, signature and optional checksum. Answers { upload_id, status: "ready", bytes }.

Required permission: videos:write

Use after storage acknowledges the final bytes, before complete_by. A lost response can be retried with the same upload_id. upload_not_ready means the upload is incomplete, expired or unavailable. Completion preserves the original preparation expiry; it does not grant an extra hour. No project is created and no credits are spent by completion.

Inputs

Example request

{
  "name": "complete_reference_upload",
  "arguments": {
    "upload_id": "upload-id"
  }
}

Result · structuredContent

{
  "upload_id": "upload-id",
  "status": "ready",
  "bytes": 123456
}

Errors

unauthorized, permission_denied, not_found, invalid_request, upload_not_ready, rate_limited, internal_error, temporarily_unavailable.

create_seedance_task

Generate a clip with Seedance 2.5 (dreamina-seedance-2-5-260628), in BytePlus ModelArk's own request shape. Returns the task id at once; poll get_seedance_task until it succeeds or fails. Costs exactly BytePlus's price, one credit per US dollar.

Required permission: videos:write

A BytePlus client only changes its base URL to {origin}/api/v1/seedance and its key. The price is BytePlus's list price for the tokens the clip used; when BytePlus can't make a task, the same task is made by another provider at the same price. Nothing made, nothing charged. The most a task could cost is held while it runs. Reuse request_id and the same body to retry without a second task.

Inputs

Example request

{
  "name": "create_seedance_task",
  "arguments": {
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "A red kite over a beach at dusk, slow push-in"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/first-frame.jpg"
        },
        "role": "first_frame"
      }
    ],
    "resolution": "1080p",
    "duration": 6,
    "request_id": "kite-001"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-123456789abc",
  "model": "dreamina-seedance-2-5-260628",
  "status": "queued",
  "created_at": 1793361600,
  "updated_at": 1793361600,
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": 6,
  "framespersecond": 24,
  "generate_audio": true,
  "credits": {
    "price": null,
    "charged": null,
    "reserved": 4.89
  },
  "poll_after_seconds": 10
}

Errors

unauthorized, permission_denied, not_found, invalid_request, insufficient_credits, allowance_exhausted, cap_too_low, idempotency_conflict, rate_limited, internal_error, temporarily_unavailable.

get_seedance_task

Get a Seedance task in BytePlus's task shape: its status, and when it succeeded the clip's link, the tokens it used and its price in credits. While queued or running, wait poll_after_seconds before checking again.

Required permission: projects:read

Terminal states are succeeded and failed; a failed task's error says why, and it was not charged. content.video_url is a Ghostmotion link that expires after one hour: read the task again for a fresh one. It follows a redirect to temporary storage and needs no bearer header.

Inputs

Example request

{
  "name": "get_seedance_task",
  "arguments": {
    "task_id": "0190e2c4-1b2c-4d3e-8f40-123456789abc"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-123456789abc",
  "model": "dreamina-seedance-2-5-260628",
  "status": "succeeded",
  "created_at": 1793361600,
  "updated_at": 1793361600,
  "resolution": "1080p",
  "ratio": "adaptive",
  "duration": 6,
  "framespersecond": 24,
  "generate_audio": true,
  "credits": {
    "price": 3.435413,
    "charged": 3.435413,
    "reserved": 0
  },
  "content": {
    "video_url": "https://app.ghostmotion.ai/api/v1/media/example-token",
    "video_url_expires_at": "2026-11-01T13:02:00.000Z"
  },
  "usage": {
    "completion_tokens": 293625,
    "total_tokens": 293625
  }
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.

create_seedream_task

Generate or edit images with Seedream 5.0 (Pro, Lite or Flash) in BytePlus ModelArk's own images/generations request shape. Returns a task id at once; poll get_seedream_task until it succeeds or fails. Costs exactly BytePlus's list price per image, one credit per US dollar.

Required permission: videos:write

Unlike BytePlus's synchronous call, this returns a task to poll. BytePlus's prices: Pro $0.045 an image up to 2.61 million pixels (1.5K) and $0.09 above, plus $0.003 for each reference image after the first; Lite $0.035; Flash $0.018. Reference images are public https URLs (image, up to 10). Lite alone makes sets: with sequential_image_generation auto, up to max_images related images, each charged. When BytePlus can't make a task, the same task is made on another provider at BytePlus's price. Nothing made, nothing charged. Reuse request_id and the same body to retry.

Inputs

Example request

{
  "name": "create_seedream_task",
  "arguments": {
    "model": "dola-seedream-5-0-pro-260628",
    "prompt": "A paper-cut lighthouse on a stormy coast, warm window light",
    "size": "2K",
    "request_id": "lighthouse-001"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-223456789abc",
  "model": "dola-seedream-5-0-pro-260628",
  "status": "queued",
  "created": 1793361600,
  "size": "2K",
  "credits": {
    "price": null,
    "charged": null,
    "reserved": 0.09
  },
  "poll_after_seconds": 5
}

Errors

unauthorized, permission_denied, not_found, invalid_request, insufficient_credits, allowance_exhausted, cap_too_low, idempotency_conflict, rate_limited, internal_error, temporarily_unavailable.

get_seedream_task

Get a Seedream task: its status, and when it succeeded BytePlus's response shape (data[].url, usage.generated_images) and its price in credits.

Required permission: projects:read

Each data[].url is a Ghostmotion link that expires after one hour: read the task again for fresh ones. A failed task's error says why; it was not charged.

Inputs

Example request

{
  "name": "get_seedream_task",
  "arguments": {
    "task_id": "0190e2c4-1b2c-4d3e-8f40-223456789abc"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-223456789abc",
  "model": "dola-seedream-5-0-pro-260628",
  "status": "succeeded",
  "created": 1793361600,
  "size": "2K",
  "credits": {
    "price": 0.045,
    "charged": 0.045,
    "reserved": 0
  },
  "data": [
    {
      "url": "https://app.ghostmotion.ai/api/v1/media/example-token",
      "size": "2048x2048"
    }
  ],
  "url_expires_at": "2026-11-01T13:02:00.000Z",
  "usage": {
    "generated_images": 1
  }
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.

create_gemini_task

Generate an image with Nano Banana 2.1 (gemini-nano-banana-2.1) or a video with Gemini Omni Flash 1.1 (gemini-omni-1.1-flash), with the Gemini API's own contents and generationConfig. Returns a task id at once; poll get_gemini_task until it succeeds or fails. Costs exactly Google's list price, one credit per US dollar.

Required permission: videos:write

Media are file_data parts with a public https file_uri; inline_data is refused. Nano Banana takes generationConfig.imageConfig (aspectRatio, imageSize 1K or 2K); Omni Flash takes generationConfig.videoConfig (aspectRatio 16:9 or 9:16, resolution 720p, durationSeconds 3 to 10, task generate, edit or extend). Each is charged exactly what Google bills: the tokens Google counts for it (input, text and thinking, and the image or video) at Google's list prices, shown in usage.tokens. A 1K image is about $0.04; 720p video about $0.10 a second. Sizes and resolutions Google publishes no single price for are not offered yet. When Google can't make a task, the same task is made on another provider at Google's price. Nothing made, nothing charged.

Inputs

Example request

{
  "name": "create_gemini_task",
  "arguments": {
    "model": "gemini-nano-banana-2.1",
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Turn this sketch into a glossy product photo on white"
          },
          {
            "file_data": {
              "file_uri": "https://example.com/sketch.png",
              "mime_type": "image/png"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "2K"
      }
    },
    "request_id": "sketch-001"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-323456789abc",
  "model": "gemini-nano-banana-2.1",
  "status": "queued",
  "createTime": "2026-11-01T12:00:00.000Z",
  "credits": {
    "price": null,
    "charged": null,
    "reserved": 0.0504
  },
  "poll_after_seconds": 5
}

Errors

unauthorized, permission_denied, not_found, invalid_request, insufficient_credits, allowance_exhausted, cap_too_low, idempotency_conflict, rate_limited, internal_error, temporarily_unavailable.

get_gemini_task

Get a Nano Banana or Omni Flash task: its status, and when it succeeded the image or video as file_data parts in the Gemini API's candidate shape, with usage and its price in credits.

Required permission: projects:read

Each file_uri is a Ghostmotion link that expires after one hour: read the task again for fresh ones. A failed task's error says why; it was not charged.

Inputs

Example request

{
  "name": "get_gemini_task",
  "arguments": {
    "task_id": "0190e2c4-1b2c-4d3e-8f40-323456789abc"
  }
}

Result · structuredContent

{
  "id": "0190e2c4-1b2c-4d3e-8f40-323456789abc",
  "model": "gemini-nano-banana-2.1",
  "status": "succeeded",
  "createTime": "2026-11-01T12:00:00.000Z",
  "credits": {
    "price": 0.0504,
    "charged": 0.0504,
    "reserved": 0
  },
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "file_data": {
              "file_uri": "https://app.ghostmotion.ai/api/v1/media/example-token",
              "mime_type": "image/png"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "uri_expires_at": "2026-11-01T13:02:00.000Z",
  "usage": {
    "images": 1
  }
}

Errors

unauthorized, permission_denied, not_found, rate_limited, internal_error, temporarily_unavailable.