HTTP API reference

Create a video

POST /api/v1/videos

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.

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/videos" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Response · 202

{
  "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.

Edit or continue a video

POST /api/v1/projects/{project_id}/messages

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.

Path parameters

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/projects/$PROJECT_ID/messages" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "launch-edit-001",
  "message": "Make the opening faster and add captions."
}'

Response · 202

{
  "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.

Check a run and get results

GET /api/v1/runs/{run_id}

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.

Path parameters

Query parameters

No query parameters required.

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/runs/$RUN_ID" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

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

GET /api/v1/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.

Query parameters

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/projects?limit=20" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

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

GET /api/v1/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.

Query parameters

No query parameters required.

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/characters" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

{
  "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 a character

POST /api/v1/characters

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.

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/characters" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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."
}'

Response · 202

{
  "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 a run

POST /api/v1/runs/{run_id}/stop

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.

Path parameters

Request body

No JSON body required.

Example request

curl --fail-with-body -X POST "https://app.ghostmotion.ai/api/v1/runs/$RUN_ID/stop" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

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

Errors

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

Prepare a reference upload

POST /api/v1/reference-uploads

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.

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/reference-uploads" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "logo.png",
  "content_type": "image/png"
}'

Response · 201

{
  "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 a direct reference upload

POST /api/v1/reference-uploads/{upload_id}/complete

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.

Path parameters

Request body

No JSON body required.

Example request

curl --fail-with-body -X POST "https://app.ghostmotion.ai/api/v1/reference-uploads/{upload_id}/complete" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

{
  "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 a Seedance video

POST /api/v1/seedance/contents/generations/tasks

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.

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/seedance/contents/generations/tasks" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Response · 200

{
  "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.

Check a Seedance video

GET /api/v1/seedance/contents/generations/tasks/{task_id}

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.

Path parameters

Query parameters

No query parameters required.

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/seedance/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

{
  "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 images

POST /api/v1/seedream/images/generations

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.

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/seedream/images/generations" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Response · 200

{
  "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.

Check Seedream images

GET /api/v1/seedream/images/generations/{task_id}

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.

Path parameters

Query parameters

No query parameters required.

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/seedream/images/generations/$TASK_ID" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

{
  "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 a Nano Banana image or Omni Flash video

POST /api/v1/gemini/models/{model}/tasks

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.

Path parameters

Request body

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/gemini/models/gemini-nano-banana-2.1/tasks" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

Response · 200

{
  "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.

Check a Nano Banana or Omni Flash task

GET /api/v1/gemini/tasks/{task_id}

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.

Path parameters

Query parameters

No query parameters required.

Example request

curl --fail-with-body "https://app.ghostmotion.ai/api/v1/gemini/tasks/$TASK_ID" \
  -H "Authorization: Bearer $GHOSTMOTION_API_KEY"

Response · 200

{
  "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.

Upload and download URLs

The upload_url returned by the upload endpoint is a private Google Cloud Storage upload session: PUT the raw bytes there with the returned headers and keep the URL intact. Storage answers 200 or 201 once it has the whole file. complete_reference_upload answers upload_id, status: "ready" and bytes.

GET /api/v1/media/{token} retrieves a film using the opaque URL returned by a run. Follow redirects; the server may issue a 307 to temporary object-storage access. Add ?download=1 to request an attachment. No extra bearer header is needed for these signed URLs. They still depend on the issuing key and current project access.

Never publish signed URLs or treat them as permanent links. See the upload guide for the complete file workflow.