Build with GoMotion

Turn a script, or your own voiceover, into a finished documentary-style video from your code, from n8n or Make, or from an AI agent like Claude or Cursor. Same videos, same credits as the studio.

Quickstart

Your first video in three steps. Each program creates a short video, waits for it, exports the MP4 and prints the download link. These exact files run in our test suite before every release.

1. Create an API key

   In the app, open API & MCP and click Create API key. It is shown once: store it somewhere safe.

   Open API & MCP
2. Put it in your environment

   export GOMOTION_API_KEY="gmk_live_..."

3. Run one of these
   curlPythonJavaScript

   #!/usr/bin/env bash
   # GoMotion API quickstart (curl + jq): script -> video -> MP4 download link
   set -euo pipefail
   API=https://gomotionai.com/v1
   AUTH="Authorization: Bearer $GOMOTION_API_KEY"
   
   # 1. Create the video (the Idempotency-Key makes a retry safe: it never charges twice)
   VIDEO=$(curl --fail-with-body -sS -X POST "$API/videos" -H "$AUTH" -H "Content-Type: application/json" \
     -H "Idempotency-Key: quickstart-$(date +%s)" \
     -d '{"script": "In 1969, three astronauts left Earth on a journey nobody had made before. Four days later, two of them walked on the Moon while the whole planet watched.", "title": "Apollo 11 in 30 seconds"}')
   ID=$(echo "$VIDEO" | jq -r .id)
   echo "video $ID: $(echo "$VIDEO" | jq -r .status), $(echo "$VIDEO" | jq -r .cost_credits) credits"
   
   # 2. Wait until it is ready
   while true; do
     STATUS=$(curl --fail-with-body -sS "$API/videos/$ID" -H "$AUTH" | jq -r .status)
     echo "status: $STATUS"
     case "$STATUS" in succeeded) break;; failed|cancelled|interrupted) exit 1;; esac
     sleep 10
   done
   
   # 3. Export it to MP4 (the first export of a video is free) and wait for the link
   EXPORT=$(curl --fail-with-body -sS -X POST "$API/videos/$ID/export" -H "$AUTH" -H "Content-Type: application/json" \
     -H "Idempotency-Key: quickstart-export-$ID" -d '{"quality": "medium"}')
   EID=$(echo "$EXPORT" | jq -r .id)
   while true; do
     E=$(curl --fail-with-body -sS "$API/exports/$EID" -H "$AUTH")
     case "$(echo "$E" | jq -r .status)" in succeeded) break;; failed|cancelled|interrupted) exit 1;; esac
     sleep 10
   done
   echo "download: $(echo "$E" | jq -r .download_url)"
   

   Needs jq.

   # GoMotion API quickstart (Python 3 + requests): script -> video -> MP4 download link
   import os, time, uuid
   import requests
   
   API = "https://gomotionai.com/v1"
   s = requests.Session()
   s.headers["Authorization"] = "Bearer " + os.environ["GOMOTION_API_KEY"]
   
   
   def call(method, path, **kw):
       """One request, retrying politely on 429/503 (the API tells you how long to wait)."""
       for _ in range(6):
           r = s.request(method, API + path, timeout=60, **kw)
           if r.status_code in (429, 503) and "Retry-After" in r.headers:
               time.sleep(min(int(r.headers["Retry-After"]), 120))
               continue
           if r.status_code >= 400:
               raise SystemExit("API error %s: %s" % (r.status_code, r.json().get("error")))
           return r.json()
       raise SystemExit("API still busy (%s): try again later" % r.status_code)
   
   
   def wait(path):
       while True:
           obj = call("GET", path)
           print(obj["object"], obj["id"], obj["status"])
           if obj["status"] == "succeeded":
               return obj
           if obj["status"] in ("failed", "cancelled", "interrupted"):
               raise SystemExit("%s %s: %s" % (obj["object"], obj["status"], obj["error"]))
           time.sleep(10)
   
   
   video = call("POST", "/videos", headers={"Idempotency-Key": str(uuid.uuid4())}, json={
       "script": "In 1969, three astronauts left Earth on a journey nobody had made before. "
                 "Four days later, two of them walked on the Moon while the whole planet watched.",
       "title": "Apollo 11 in 30 seconds",
   })
   print("video", video["id"], "costs", video["cost_credits"], "credits")
   wait("/videos/" + video["id"])
   
   export = call("POST", "/videos/%s/export" % video["id"],
                 headers={"Idempotency-Key": "export-" + video["id"]}, json={"quality": "medium"})
   done = wait("/exports/" + export["id"])
   print("download:", done["download_url"])
   

   pip install requests

   // GoMotion API quickstart (Node.js 18+, no dependencies): script -> video -> MP4 download link
   import { randomUUID } from "node:crypto";
   const API = "https://gomotionai.com/v1";
   const headers = { Authorization: `Bearer ${process.env.GOMOTION_API_KEY}`, "Content-Type": "application/json" };
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
   
   async function call(method, path, body, idempotencyKey) {
     for (let i = 0; i < 6; i++) {
       const h = idempotencyKey ? { ...headers, "Idempotency-Key": idempotencyKey } : headers;
       const r = await fetch(API + path, { method, headers: h, body: body ? JSON.stringify(body) : undefined });
       if ((r.status === 429 || r.status === 503) && r.headers.get("retry-after")) {
         await sleep(Math.min(Number(r.headers.get("retry-after")), 120) * 1000);
         continue;
       }
       const data = await r.json();
       if (!r.ok) throw new Error(`${r.status}: ${data.error}`);
       return data;
     }
     throw new Error("still busy, try again later");
   }
   
   async function wait(path) {
     for (;;) {
       const obj = await call("GET", path);
       console.log(obj.object, obj.id, obj.status);
       if (obj.status === "succeeded") return obj;
       if (["failed", "cancelled", "interrupted"].includes(obj.status)) throw new Error(obj.error);
       await sleep(10000);
     }
   }
   
   const video = await call("POST", "/videos", {
     script: "In 1969, three astronauts left Earth on a journey nobody had made before. " +
             "Four days later, two of them walked on the Moon while the whole planet watched.",
     title: "Apollo 11 in 30 seconds",
   }, randomUUID());
   console.log("video", video.id, "costs", video.cost_credits, "credits");
   await wait(`/videos/${video.id}`);
   const exp = await call("POST", `/videos/${video.id}/export`, { quality: "medium" }, `export-${video.id}`);
   const done = await wait(`/exports/${exp.id}`);
   console.log("download:", done.download_url);
   

   Node.js 18+, save as quickstart.mjs.

AI agents (MCP)

GoMotion has an MCP server, so AI agents such as Claude Code, Claude Desktop and Cursor can make videos for you. Tell your agent "make me a 10-minute history video about the fall of Rome" and it writes or fetches the script, creates the video, waits for it and hands you the download link.

• Remote server: https://gomotionai.com/mcp (Streamable HTTP). Nothing to install.
• Same account, same prices. The agent uses your API key, so it gets the same credits, plan limits and permissions as the web app. Nothing extra is charged for using MCP.

1. Get an API key

Open gomotionai.com/app → API & MCP in the sidebar → Create API key. Copy it (it starts with gmk_live_); it is shown only once. API keys need a paid plan. You can give a key a daily credit cap to limit what an agent can spend per day.

2. Connect your agent

Replace gmk_live_YOUR_KEY with your key.

Claude Code

One command:

claude mcp add --transport http gomotion https://gomotionai.com/mcp \
  --header "Authorization: Bearer gmk_live_YOUR_KEY"

claude mcp list should say Connected (that only checks the connection, not the key): to check the key, ask Claude "How many GoMotion credits do I have?". Add --scope user to use it in every project.

Claude Desktop

Settings → Developer → Edit Config, then put this in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and restart Claude Desktop. It needs Node.js 20 or newer.

{
  "mcpServers": {
    "gomotion": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://gomotionai.com/mcp",
        "--header",
        "Authorization:${GOMOTION_AUTH}"
      ],
      "env": {
        "GOMOTION_AUTH": "Bearer gmk_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop runs local servers, so this uses mcp-remote (it needs Node.js 20 or newer) to connect to the remote server with your key. Restart Claude Desktop after saving.

Cursor

Put this in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "gomotion": {
      "url": "https://gomotionai.com/mcp",
      "headers": { "Authorization": "Bearer gmk_live_YOUR_KEY" }
    }
  }
}

Other MCP clients

Any client that lets you set an HTTP header for a remote MCP server: URL https://gomotionai.com/mcp, header Authorization: Bearer gmk_live_YOUR_KEY. For apps that only run local servers, use mcp-remote as in Claude Desktop above.

Quick check from a terminal (asks for your credit balance, so it also checks the key):

curl -s https://gomotionai.com/mcp -H "Authorization: Bearer gmk_live_YOUR_KEY" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_credits","arguments":{}}}'

3. Ask for a video

Example prompts:

• "Make me a 2-minute video in English about the history of the Roman aqueducts. Write the narration yourself, tell me the price first, then give me the download link."
• "Write a 10-minute script about the fall of Constantinople in the style of https://www.youtube.com/@MyFavouriteChannel, show it to me, and when I say OK turn it into a video with an epic soundtrack and the cinematic background."
• "List Spanish voices, pick a deep male narrator, and make a 5-minute video in Spanish from this script: …"
• "How many credits do I have left, and what did my last videos cost?"
• "Make a YouTube thumbnail for my video 'The Last Days of Pompeii' like the ones on https://www.youtube.com/@MyChannel."

Videos take several minutes to render. The agent gets a video id at once and then checks on it (about once a minute, or by waiting up to 50 seconds per check). If your agent cannot wait, it gives you the video id: ask again later, or find the video in the web app.

Tools

The agent also gets a ready-made prompt, make_video, with the whole flow.

Billing, limits and safety

• Everything is billed exactly like the web app, to the account that owns the key. Creating a video reserves its credits; a failed or cancelled video is refunded automatically.
• Repeating the same request within 24 hours returns the same video instead of charging again, so an agent that retries after a timeout never pays twice. If that earlier video failed or was cancelled, a new one is made. To make a second identical video on purpose (or re-export after editing the project in the web editor), the agent passes force_new.
• max_cost_credits on create_video is a hard ceiling for one video. A key's daily credit cap is checked before each new video; one video that turns out longer than estimated can still finish a little over it.
• Limits are your plan's API limits (requests per minute, videos in progress). When one is hit, the agent is told how long to wait.
• The remote server keeps nothing: it does not store your key, scripts or videos, and its logs never contain keys. It only calls GoMotion's public API (/v1) with your key (and reads the public music catalog). Keys used through the remote server show GoMotion's server as their last-used address.
• Revoke a key at any time in the web app; the agent loses access at once.
• Not available through MCP, on purpose: billing and plans, API keys, account settings, YouTube channel connection and Autopilot publishing. These stay in the web app.

Keys & authentication

Send the key on every request as Authorization: Bearer gmk_live_... (or X-API-Key: gmk_live_...). All calls are HTTPS to https://gomotionai.com/v1 with JSON bodies.

• Create, name and revoke keys in the app (API & MCP in the sidebar). The full key is shown once; we only keep a hash and show the last 4 characters.
• Give each integration its own key, with only the permissions it needs: videos:write, videos:read, scripts:write, thumbnails:write, credits:read. Optionally set a daily credit limit per key (a good idea for AI agents).
• Never put a key in a web page or a mobile app: call the API from your server or automation tool.
• If a key leaks, revoke it: it stops working at once.

How a video is made

1. POST /v1/videos with your script (or audio_key). The price is reserved from your credits; you get an id.
2. Poll GET /v1/videos/{id} every 20–30 s. status: queued → running (with progress.percent) → succeeded, or failed/cancelled (credits come back: refunded: true). A 1-minute video usually takes a few minutes.
3. POST /v1/videos/{id}/export renders the 1080p MP4 (the first export of each video is free).
4. Poll GET /v1/exports/{id} until succeeded: download_url is a signed link valid 12 h (it is re-signed on every GET); the file is kept 48 h.

Instead of polling you can get a webhook when each step ends. Polling is free, but every call counts toward your requests-per-minute limit, so poll every 20–30 seconds.

Your own voiceover

Ask for an upload URL, PUT your audio file there, then create the video with audio_key and the length in seconds. Do the same with kind: "music" and music_key to use your own background track.

#!/usr/bin/env bash
# Your own voiceover (any common audio file) -> video
set -euo pipefail
API=https://gomotionai.com/v1
AUTH="Authorization: Bearer $GOMOTION_API_KEY"
FILE=${1:-voiceover.mp3}

# 1. Ask for an upload URL and PUT the file there (the URL is valid for 1 hour)
UP=$(curl --fail-with-body -sS -X POST "$API/uploads" -H "$AUTH" -H "Content-Type: application/json" -d '{"kind": "audio"}')
curl --fail-with-body -sS -X PUT --upload-file "$FILE" "$(echo "$UP" | jq -r .put_url)"

# 2. Create the video: duration_sec = length of your audio (you are billed on the real length)
SECONDS_LONG=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$FILE" | cut -d. -f1)
curl --fail-with-body -sS -X POST "$API/videos" -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: voice-$(date +%s)" \
  -d "{\"audio_key\": \"$(echo "$UP" | jq -r .key)\", \"duration_sec\": $SECONDS_LONG, \"title\": \"My narrated video\"}" | jq '{id, status, cost_credits}'

AI scripts & thumbnails

Scripts and thumbnails are written in the style of a YouTube channel you pick (channel_url, or up to 3 video_ids). With only a topic, we search YouTube for it and use 3 videos as references (same price; references_source: "topic_search"). They run in the background: POST returns 202 with an id; poll GET /v1/scripts/{id}.

# Write a script with AI in the style of a YouTube channel, then turn it into a video
import os, time, uuid
import requests

API = "https://gomotionai.com/v1"
H = {"Authorization": "Bearer " + os.environ["GOMOTION_API_KEY"]}


def ok(r):
    if r.status_code >= 400:
        raise SystemExit("API error %s: %s" % (r.status_code, r.json().get("error")))
    return r.json()


task = ok(requests.post(API + "/scripts", headers=dict(H, **{"Idempotency-Key": str(uuid.uuid4())}), json={
    "channel_url": "https://www.youtube.com/@NASA",
    "topic": "How the James Webb telescope unfolded in space",
    "minutes": 1,
}, timeout=60))
while task["status"] == "running":
    time.sleep(10)
    task = ok(requests.get(API + "/scripts/" + task["id"], headers=H, timeout=60))
if task["status"] != "succeeded":
    raise SystemExit(task["error"])
print(task["result"]["title"], "-", task["result"]["words"], "words")

video = ok(requests.post(API + "/videos", headers=dict(H, **{"Idempotency-Key": str(uuid.uuid4())}),
                         json={"script": task["result"]["script"], "title": task["result"]["title"]}, timeout=60))
print("video", video["id"], video["status"])

n8n & Make templates

Ready-to-import workflows for topic in a Google Sheet → GoMotion video → download link back in the sheet.

Download the n8n workflow Download the Make blueprint

• n8n: Workflows → Import from file. Create a Header Auth credential named GoMotion API key with name Authorization and value Bearer gmk_live_..., and connect your Google Sheets credential.
• Make: Create a new scenario → … → Import Blueprint. Put your key in the Authorization header of the HTTP modules and pick your sheet.
• Zapier: use Webhooks by Zapier with the same four calls (create, poll, export, poll).

The sheet needs columns topic, channel_url, script, title, status, video_id, download_url, error and (optional) voice — a voice id from GET /v1/voices. Rows with a script go straight to a video; rows with only a topic get an AI script first, written in the style of the YouTube channel in channel_url (required for topic rows). If a row fails, the template writes failed and the reason in error; clear status to try that row again.

Webhooks

Get a POST on your server when a video, export, script or thumbnail created by your key ends. Add an endpoint with POST /v1/webhooks (up to 3 per key). The answer includes the signing secret: it is shown only there and on rotate-secret.

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://yourshop.com/gomotion/webhook", "events": ["video.succeeded", "video.failed", "export.succeeded", "export.failed"]}'

Events: video.succeeded, video.failed, video.cancelled, export.succeeded, export.failed, export.cancelled, script.succeeded, script.failed, thumbnail.succeeded, thumbnail.failed (default: all). Each POST body is an event whose data.object is the same object GET /v1/videos/{id}, /v1/exports/{id}, /v1/scripts/{id} or /v1/thumbnails/{id} returns:

{
  "api_version": "2026-11-01",
  "created_at": 1793535293,
  "data": {
    "object": {
      "cost_credits": 0,
      "created_at": 1793535290,
      "download_filename": "Acme Films - order 0.mp4",
      "download_url": "https://<account>.r2.cloudflarestorage.com/gomotion/t/t_5f3a91c2e4b7/downloads/j_73776a5038734181.mp4?X-Amz-Signature=...&response-content-disposition=attachment%3B%20filename%3D%22Acme%20Films%20-%20order%200.mp4%22",
      "download_url_expires_in_s": 43200,
      "error": null,
      "external_id": "ord-0",
      "id": "j_73776a5038734181",
      "metadata": {
        "n": "0",
        "order_id": "o0",
        "shop": "acme"
      },
      "object": "export",
      "progress": {
        "eta_s": 0,
        "percent": 100,
        "phase": "Completed"
      },
      "project_id": "p_d47e376ac26f",
      "queue_position": null,
      "refunded": false,
      "status": "succeeded",
      "updated_at": 1793535291
    }
  },
  "id": "evt_5f3a91c2e4b74e64916c",
  "object": "event",
  "type": "export.succeeded"
}

Verify the signature

Header GoMotion-Signature: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256 of "<t>.<raw body>" with your secret. Use the raw body bytes, compare in constant time and reject t older than 5 minutes. This exact code runs in our test suite.

import crypto from "node:crypto";

// rawBody: the request bytes exactly as received (e.g. express.raw({ type: "application/json" })).
// header: the GoMotion-Signature header.
export function verifyGoMotion(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib, hmac, time


def verify_gomotion(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """raw_body: the request bytes exactly as received. header: GoMotion-Signature."""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

• Answer 2xx within 10 s and do the work afterwards. Otherwise we retry at +30 s, 2 min, 10 min, 30 min, 2 h, 6 h and 12 h (8 attempts).
• Dedupe on the event id (id, also in GoMotion-Event-Id): retries keep the same id. Order is not guaranteed.
• Webhooks are a hint: GET is the truth, and polling keeps working as before.
• 25 events in a row that use all attempts disable the endpoint (status: "disabled"); turn it back on with POST /v1/webhooks/{id} and {"enabled": true}.
• POST /v1/webhooks/{id}/test sends a signed webhook.test now; GET /v1/webhooks/{id}/deliveries shows the last attempts; POST /v1/webhooks/{id}/deliveries/{evt}/retry sends one again.
• URL: https:// on port 443 with a public host name. No redirects are followed.

Build on GoMotion / resell

Sell videos under your own brand. Your customer talks to your site; only your backend talks to GoMotion.

1. Your site takes the order. Your backend (it holds the API key, never the browser) calls POST /v1/videos with external_id (your order id) and metadata (up to 20 keys). Both come back on every object and webhook.
2. Wait for the video.succeeded webhook, or poll GET /v1/videos/{id}.
3. POST /v1/videos/{id}/export with download_filename (e.g. "Acme Films - order 1001"): the MP4 downloads with your name, not ours.
4. On export.succeeded, download the MP4 from download_url and store it on your own storage. The link lasts 12 h and the file 48 h: never give our link to your customer.

Find orders later with GET /v1/videos?external_id=order-1001 or ?metadata[shop]=acme (also on GET /v1/exports). Page with starting_after = next_starting_after of the previous page.

Reseller credit pack

0.0125 USD per credit, minimum 20,000 credits (250 USD). A video costs the same credits as in the app: voice quality, length, thumbnails and AI scripts change the total, so quote each order with GET /v1/quote before you set your price. Questions and bigger limits: support@gomotionai.com.

Good to know

• Music catalog (for music_track = "<mood>/<file>"): gomotionai.com/music/catalog.json, public.
• Cancel works on queued or running jobs; on a finished one it returns the object unchanged. A cancel shows in GET /v1/credits/history as a hold and then a refund with the same job_id.
• Upload with a plain PUT of the file body to put_url from your server (no extra headers). A script_key can be reused for 60 h.
• Script and thumbnail tasks can't be cancelled; a failed one refunds its credits (credits_refunded).
• Idempotency-Key is 8-64 characters: for longer ids (e.g. Stripe session ids) send a hash.
• Webhook signatures are over the RAW request body: in no-code tools, keep the raw body (don't re-serialise the JSON) before you check GoMotion-Signature.

Credits per call

Your own voiceover is billed on its real length, measured by our server. Using the API or MCP costs nothing extra.

Limits per plan

Generous by design: these are safety rails, not a paywall.

When you hit one you get 429 with a Retry-After header. GET /v1/account shows your current limits and today's usage of the key.

Need higher limits? Email support@gomotionai.com with what you are building and the volume you need, and we will raise them. Then custom_limits is true in GET /v1/account.

Idempotency

Never pay twice for the same request. Every call that spends credits (POST /v1/videos, /export, /v1/scripts, /v1/thumbnails) needs an Idempotency-Key header: any unique string (8–64 letters, digits, - or _), e.g. a UUID or your own row id. If a request times out, send it again with the same key and body: you get the same video back (200) instead of a new charge. The same key with a different body is a 409. Keys are remembered 24 h. If your own id is longer than 64 characters, send a hash of it.

Errors

Errors are JSON: {"error": "message", ...}. Newer errors also carry a stable code.

{
  "error": "daily credit cap reached for this key",
  "cap": 170,
  "spent": 75,
  "needed": 207,
  "retry_after": 41319
}

Endpoint reference

Base URL https://gomotionai.com. Machine-readable: /openapi.json (OpenAPI 3.1).

Videos

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/videos" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"script": "In 1969, three astronauts left Earth...", "title": "Apollo 11", "voice": "aurora", "background": "cinematic", "music_style": "documentary"}'

{
  "cost_credits": 75,
  "created_at": 1793535286,
  "error": null,
  "estimated_duration_sec": 32.0,
  "external_id": "ord-0",
  "id": "j_a384eca193e1458f",
  "metadata": {
    "n": "0",
    "order_id": "o0",
    "shop": "acme"
  },
  "object": "video",
  "progress": null,
  "project_id": null,
  "queue_position": null,
  "refunded": false,
  "status": "running",
  "updated_at": 1793535286
}

curl --fail-with-body -sS "https://gomotionai.com/v1/videos?limit=10&status=succeeded" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "data": [
    {
      "cost_credits": 75,
      "created_at": 1793535286,
      "error": null,
      "estimated_duration_sec": 32.0,
      "external_id": "ord-0",
      "id": "j_a384eca193e1458f",
      "metadata": {
        "n": "0",
        "order_id": "o0",
        "shop": "acme"
      },
      "object": "video",
      "progress": {
        "eta_s": 0,
        "percent": 100,
        "phase": "Completed"
      },
      "project_id": "p_d47e376ac26f",
      "queue_position": null,
      "refunded": false,
      "status": "succeeded",
      "updated_at": 1793535287
    },
    {
      "cost_credits": 75,
      "created_at": 1793535286,
      "error": null,
      "estimated_duration_sec": 32.0,
      "external_id": "ord-1",
      "id": "j_a92d9fc8e6ab428c",
      "metadata": {
        "n": "1",
        "order_id": "o1",
        "shop": "acme"
      },
      "object": "video",
      "progress": {
        "eta_s": 0,
        "percent": 100,
        "phase": "Completed"
      },
      "project_id": "p_28f68f8f6ba1",
      "queue_position": null,
      "refunded": false,
      "status": "succeeded",
      "updated_at": 1793535288
    }
  ],
  "has_more": true,
  "next_starting_after": "j_a92d9fc8e6ab428c",
  "object": "list"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "cost_credits": 75,
  "created_at": 1793535286,
  "error": null,
  "estimated_duration_sec": 32.0,
  "external_id": "ord-0",
  "id": "j_a384eca193e1458f",
  "metadata": {
    "n": "0",
    "order_id": "o0",
    "shop": "acme"
  },
  "object": "video",
  "progress": null,
  "project_id": null,
  "queue_position": null,
  "refunded": false,
  "status": "running",
  "updated_at": 1793535286
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/jobs/$VIDEO_ID/cancel" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "cost_credits": 75,
  "created_at": 1793535298,
  "error": null,
  "estimated_duration_sec": 33.0,
  "external_id": null,
  "id": "j_89ece89df61c47aa",
  "metadata": {},
  "object": "video",
  "progress": null,
  "project_id": null,
  "queue_position": null,
  "refunded": true,
  "status": "cancelled",
  "updated_at": 1793535298
}

Exports

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/videos/$VIDEO_ID/export" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"quality": "high", "download_filename": "Acme Films - order 1001"}'

{
  "cost_credits": 0,
  "created_at": 1793535290,
  "download_filename": null,
  "download_url": null,
  "download_url_expires_in_s": null,
  "error": null,
  "external_id": "ord-0",
  "id": "j_73776a5038734181",
  "metadata": {
    "n": "0",
    "order_id": "o0",
    "shop": "acme"
  },
  "object": "export",
  "progress": null,
  "project_id": "p_d47e376ac26f",
  "queue_position": null,
  "refunded": false,
  "status": "running",
  "updated_at": 1793535290
}

curl --fail-with-body -sS "https://gomotionai.com/v1/exports?limit=10&external_id=order-1001" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "data": [
    {
      "cost_credits": 0,
      "created_at": 1793535290,
      "download_filename": "Acme Films - order 0.mp4",
      "download_url": "https://<account>.r2.cloudflarestorage.com/gomotion/t/t_5f3a91c2e4b7/downloads/j_73776a5038734181.mp4?X-Amz-Signature=...&response-content-disposition=attachment%3B%20filename%3D%22Acme%20Films%20-%20order%200.mp4%22",
      "download_url_expires_in_s": 43200,
      "error": null,
      "external_id": "ord-0",
      "id": "j_73776a5038734181",
      "metadata": {
        "n": "0",
        "order_id": "o0",
        "shop": "acme"
      },
      "object": "export",
      "progress": {
        "eta_s": 0,
        "percent": 100,
        "phase": "Completed"
      },
      "project_id": "p_d47e376ac26f",
      "queue_position": null,
      "refunded": false,
      "status": "succeeded",
      "updated_at": 1793535291
    }
  ],
  "has_more": true,
  "next_starting_after": "j_73776a5038734181",
  "object": "list"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "cost_credits": 0,
  "created_at": 1793535290,
  "download_filename": null,
  "download_url": null,
  "download_url_expires_in_s": null,
  "error": null,
  "external_id": "ord-0",
  "id": "j_73776a5038734181",
  "metadata": {
    "n": "0",
    "order_id": "o0",
    "shop": "acme"
  },
  "object": "export",
  "progress": null,
  "project_id": "p_d47e376ac26f",
  "queue_position": null,
  "refunded": false,
  "status": "running",
  "updated_at": 1793535290
}

Uploads

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/uploads/script" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Content-Type: application/json" -d '{"text": "In 1969 three astronauts left Earth on a journey nobody had made before. Four days later two of them walked on the Moon while the whole planet watched on television.In 1969 three astronauts left Earth on a journey nobody had made before. Four days later two of them walked on the Moon while the whole planet watched on television.In 1969 three astronauts left Earth on a journey nobody had made before. Four days later two of them walked on the Moon while the whole planet watched on television.In 1969 three astronauts left Earth on a journey nobody had made before. Four days later two of them walked on the Moon while the whole planet watched on television.In 1969 three astronauts left Earth on a journey nobody had made before. Four days later two of them walked on the Moon while the whole planet watched on television."}'

{
  "key": "t/t_5f3a91c2e4b7/uploads/136ae2dbcc2a/script.txt",
  "chars": 825,
  "expires_in_hours": 60
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/uploads" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Content-Type: application/json" -d '{"kind": "audio"}'

{
  "object": "upload",
  "kind": "audio",
  "key": "t/t_5f3a91c2e4b7/uploads/40a30b320493/audio.mp3",
  "put_url": "https://<account>.r2.cloudflarestorage.com/gomotion/t/t_5f3a91c2e4b7/uploads/40a30b320493/audio.mp3?X-Amz-Signature=...",
  "method": "PUT",
  "expires_in_s": 3600,
  "max_bytes": 100663296
}

Voices

curl --fail-with-body -sS "https://gomotionai.com/v1/languages" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "model": "vega",
      "chars_per_min": 998,
      "quality": "standard"
    },
    {
      "code": "nl",
      "name": "Dutch",
      "model": "nova",
      "chars_per_min": 774,
      "quality": "high"
    },
    {
      "code": "fr",
      "name": "French",
      "model": "nova",
      "chars_per_min": 812,
      "quality": "high"
    }
  ]
}

curl --fail-with-body -sS "https://gomotionai.com/v1/voices?lang=en&quality=standard" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "lang": "en",
  "voices": [
    {
      "id": "aurora",
      "name": "Aurora",
      "gender": "female",
      "age": "",
      "style": "",
      "region": "US",
      "model": "vega",
      "sample_url": "https://static-files.genaipro.io/vega-samples/aurora.mp3",
      "quality": "standard"
    },
    {
      "id": "luna",
      "name": "Luna",
      "gender": "female",
      "age": "",
      "style": "",
      "region": "US",
      "model": "vega",
      "sample_url": "https://static-files.genaipro.io/vega-samples/luna.mp3",
      "quality": "standard"
    },
    {
      "id": "stella",
      "name": "Stella",
      "gender": "female",
      "age": "",
      "style": "",
      "region": "UK",
      "model": "vega",
      "sample_url": "https://static-files.genaipro.io/vega-samples/stella.mp3",
      "quality": "standard"
    }
  ]
}

Scripts & thumbnails

curl --fail-with-body -sS "https://gomotionai.com/v1/references?channel_url=https://www.youtube.com/@NASA" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "object": "references",
  "type": "channel",
  "sort": "recent",
  "videos": [
    {
      "id": "dQw4w9WgXcA",
      "title": "Reference video 0",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcA",
      "thumbnail_url": null,
      "duration_sec": 600,
      "views": 0
    },
    {
      "id": "dQw4w9WgXcB",
      "title": "Reference video 1",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcB",
      "thumbnail_url": null,
      "duration_sec": 601,
      "views": 1000
    },
    {
      "id": "dQw4w9WgXcC",
      "title": "Reference video 2",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcC",
      "thumbnail_url": null,
      "duration_sec": 602,
      "views": 2000
    }
  ],
  "credits": {
    "script": 4,
    "thumbnail": 4
  },
  "included_in_plan_left": {
    "scripts": 0,
    "thumbnails": 0
  }
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/scripts" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"channel_url": "https://www.youtube.com/@NASA", "topic": "How Webb unfolded in space", "minutes": 1}'

{
  "created_at": 1793535294,
  "error": null,
  "external_id": "scr-1",
  "id": "scr_8c6265cf04fa45fd",
  "metadata": {
    "o": "1"
  },
  "object": "script",
  "references_source": "topic_search",
  "result": null,
  "status": "running",
  "updated_at": 1793535294
}

curl --fail-with-body -sS "https://gomotionai.com/v1/scripts/$SCRIPT_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "created_at": 1793535294,
  "error": null,
  "external_id": "scr-1",
  "id": "scr_8c6265cf04fa45fd",
  "metadata": {
    "o": "1"
  },
  "object": "script",
  "references_source": "topic_search",
  "result": null,
  "status": "running",
  "updated_at": 1793535294
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/thumbnails" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"title": "Webb unfolds", "video_ids": ["dQw4w9WgXcQ"]}'

{
  "created_at": 1793535297,
  "error": null,
  "external_id": "thm-1",
  "id": "thm_09a9e88bc6094f11",
  "metadata": {
    "o": "2"
  },
  "object": "thumbnail",
  "result": null,
  "status": "running",
  "updated_at": 1793535297
}

curl --fail-with-body -sS "https://gomotionai.com/v1/thumbnails/$THUMBNAIL_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "created_at": 1793535297,
  "error": null,
  "external_id": "thm-1",
  "id": "thm_09a9e88bc6094f11",
  "metadata": {
    "o": "2"
  },
  "object": "thumbnail",
  "result": null,
  "status": "running",
  "updated_at": 1793535297
}

Webhooks

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://yourshop.com/gomotion/webhook", "events": ["video.succeeded", "video.failed", "export.succeeded", "export.failed"]}'

{
  "created_at": 1793535285,
  "description": "drift",
  "disabled_reason": null,
  "events": [
    "video.succeeded",
    "video.failed",
    "video.cancelled",
    "export.succeeded",
    "export.failed",
    "export.cancelled",
    "script.succeeded",
    "script.failed",
    "thumbnail.succeeded",
    "thumbnail.failed"
  ],
  "failed_in_a_row": 0,
  "id": "wh_a0f047599f69410c",
  "last_failure_at": null,
  "last_success_at": null,
  "object": "webhook",
  "secret": "whsec_...",
  "status": "enabled",
  "url": "https://hooks.yourshop.com/drift/hook"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/webhooks" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "data": [
    {
      "created_at": 1793535285,
      "description": "drift",
      "disabled_reason": null,
      "events": [
        "video.succeeded",
        "video.failed",
        "video.cancelled",
        "export.succeeded",
        "export.failed",
        "export.cancelled",
        "script.succeeded",
        "script.failed",
        "thumbnail.succeeded",
        "thumbnail.failed"
      ],
      "failed_in_a_row": 0,
      "id": "wh_a0f047599f69410c",
      "last_failure_at": null,
      "last_success_at": null,
      "object": "webhook",
      "status": "enabled",
      "url": "https://hooks.yourshop.com/drift/hook"
    }
  ],
  "object": "list"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "created_at": 1793535285,
  "description": "drift",
  "disabled_reason": null,
  "events": [
    "video.succeeded",
    "video.failed",
    "video.cancelled",
    "export.succeeded",
    "export.failed",
    "export.cancelled",
    "script.succeeded",
    "script.failed",
    "thumbnail.succeeded",
    "thumbnail.failed"
  ],
  "failed_in_a_row": 0,
  "id": "wh_a0f047599f69410c",
  "last_failure_at": null,
  "last_success_at": null,
  "object": "webhook",
  "status": "enabled",
  "url": "https://hooks.yourshop.com/drift/hook"
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY" \
  -H "Content-Type: application/json" -d '{"enabled": true}'

{
  "created_at": 1793535285,
  "description": "drift 2",
  "disabled_reason": null,
  "events": [
    "video.succeeded",
    "video.failed",
    "video.cancelled",
    "export.succeeded",
    "export.failed",
    "export.cancelled",
    "script.succeeded",
    "script.failed",
    "thumbnail.succeeded",
    "thumbnail.failed"
  ],
  "failed_in_a_row": 0,
  "id": "wh_a0f047599f69410c",
  "last_failure_at": null,
  "last_success_at": null,
  "object": "webhook",
  "status": "enabled",
  "url": "https://hooks.yourshop.com/drift/hook"
}

curl --fail-with-body -sS -X DELETE "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "deleted": true,
  "id": "wh_120f20b244eb403b",
  "object": "webhook"
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "delivered": true,
  "error": null,
  "event_id": "evt_5f3a91c2e4b74206a566",
  "object": "webhook_test",
  "status_code": 200
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "created_at": 1793535285,
  "description": "drift 2",
  "disabled_reason": null,
  "events": [
    "video.succeeded",
    "video.failed",
    "video.cancelled",
    "export.succeeded",
    "export.failed",
    "export.cancelled",
    "script.succeeded",
    "script.failed",
    "thumbnail.succeeded",
    "thumbnail.failed"
  ],
  "failed_in_a_row": 0,
  "id": "wh_a0f047599f69410c",
  "last_failure_at": null,
  "last_success_at": null,
  "object": "webhook",
  "secret": "whsec_...",
  "status": "enabled",
  "url": "https://hooks.yourshop.com/drift/hook"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID/deliveries?limit=10" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "data": [
    {
      "attempts": 1,
      "created_at": 1793535285,
      "delivered_at": 1793535285,
      "id": "evt_5f3a91c2e4b74206a566",
      "last_error": null,
      "last_status_code": 200,
      "next_attempt_at": null,
      "object": "webhook_delivery",
      "object_id": null,
      "status": "delivered",
      "type": "webhook.test"
    }
  ],
  "object": "list"
}

curl --fail-with-body -sS -X POST "https://gomotionai.com/v1/webhooks/$WEBHOOK_ID/deliveries/$EVENT_ID/retry" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "id": "evt_5f3a91c2e4b74206a566",
  "object": "webhook_delivery",
  "status": "pending"
}

Account

curl --fail-with-body -sS "https://gomotionai.com/v1/account" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "custom_limits": false,
  "key": {
    "credits_spent_today": 0,
    "id": "k_ae85e6baae2b",
    "max_credits_day": 0,
    "scopes": [
      "videos:read",
      "videos:write",
      "scripts:write"
    ],
    "videos_in_progress": 0,
    "videos_today": 0
  },
  "limits": {
    "active_keys_per_account": 10,
    "paid_requests_per_minute_per_account": 30,
    "requests_per_minute_per_account": 300,
    "requests_per_minute_per_key": 120,
    "scripts_and_thumbnails_in_progress_per_account": 3,
    "videos_in_progress_per_account": 3,
    "videos_in_progress_per_key": 5,
    "videos_per_day_per_account": 300,
    "videos_per_day_per_key": 200
  },
  "object": "account",
  "plan": "agency"
}

curl --fail-with-body -sS "https://gomotionai.com/v1/credits" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "balance": 2000,
  "held": 0,
  "available": 2000,
  "expires_at": 0,
  "topup_credits": 0,
  "renews_at": 0,
  "key": {
    "id": "k_0d5e1907611a",
    "max_credits_day": 0,
    "spent_today": 0
  }
}

curl --fail-with-body -sS "https://gomotionai.com/v1/credits/history?limit=10" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "object": "list",
  "data": [
    {
      "at": 1793457476,
      "type": "credit",
      "credits": 5000,
      "balance_after": 5000,
      "job_id": null
    }
  ]
}

curl --fail-with-body -sS "https://gomotionai.com/v1/quote?chars=1200&lang=en" \
  -H "Authorization: Bearer $GOMOTION_API_KEY"

{
  "duration_sec": 67,
  "lang": "en",
  "voice": null,
  "quality": "standard",
  "cost_credits": 75
}

OpenAPI

Download openapi.json

OpenAPI 3.1, API version 1.2.0. Import it in Postman, Insomnia or your code generator.