GhostShorts API docs

Overview

GhostShorts has a REST API and an MCP server, and four templates run on both: Article to Video, AI Quiz Video, Reddit Story and Text Messages. Connect either one to Claude Code, Cursor, ChatGPT or n8n and ask for a video.

The GhostShorts API creates the same videos as the app, from your own scripts, automation tools and AI agents. API keys use your plan's videos and credits; there is no separate API plan. Create a key at Settings, API keys. Keys are shown once, so store yours safely. Working with an AI agent? Copy the guide below and paste it into the chat: it has the auth, the flow, every template and every error code, generated from the API itself.

Quick start

Base URL https://api.ghostshorts.com. Send your key as Authorization: Bearer gs_live_....

# 1. Create a key at https://ghostshorts.com/app/settings/api-keys, then:
export GS_KEY=gs_live_...
curl https://api.ghostshorts.com/v1/me -H "Authorization: Bearer $GS_KEY"

# 2. Create a video (answers 202 with an id; the video is made in the background)
curl -X POST https://api.ghostshorts.com/v1/videos \
  -H "Authorization: Bearer $GS_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-first-video-001' \
  -d '{"template":"article_video","inputs":{"source":{"kind":"url","url":"https://example.com/my-post"}}}'

# 3. Check on it (or pass webhookUrl when creating). downloadUrl appears when status is "completed".
curl https://api.ghostshorts.com/v1/videos/VIDEO_ID -H "Authorization: Bearer $GS_KEY"

A video usually finishes in about a minute. Poll every 20 seconds or so, or pass webhookUrl when creating. The downloadUrl needs no key and works for 7 days, so anyone you share it with can download the file.

MCP server

The same videos, credits and limits as an MCP server at https://api.ghostshorts.com/mcp.

Claude.ai or Claude Desktop (no key needed): Settings, Connectors, Add custom connector. Name it GhostShorts, paste https://api.ghostshorts.com/mcp as the URL, leave the OAuth client fields empty, click Add, then Connect. Sign in to GhostShorts in the window that opens and click Allow. The connection uses your plan and credits; disconnect it any time in Settings, API keys, Connected apps.

Claude Code, with an API key, one command:

claude mcp add --transport http ghostshorts https://api.ghostshorts.com/mcp --header "Authorization: Bearer gs_live_..."

Cursor: add GhostShorts to Cursor, then replace gs_live_... with your key (Settings, API keys shows this link with your key filled in). n8n and other clients: the MCP section of the guide above has the settings.

Templates

Each template has its own page with what it makes, its inputs, an example request and its full guide.

• Reddit Story Video APIreddit_story
• Fake Text Message Video APIfake_text_message
• Quiz Video APIquiz_video
• Article to Video APIarticle_video

Each template's full input schema and defaults are at api.ghostshorts.com/v1/templates, and the voices, backgrounds and music to pick from at api.ghostshorts.com/v1/options. Both are public: no key needed. Check a cost before you spend it with POST /v1/estimate. Every video is a 1080x1920 (9:16) MP4.

Your own media

Pass your own background footage or music by public https URL instead of a library pick. On Text Messages that is background.ownUrl and music.ownUrl; on Reddit Story, backgroundVideoUrl and backgroundAudioUrl.

• Video: up to 300 MB and 10 minutes. Converted to 9:16 H.264 for rendering, cropped to fill.
• Audio: up to 30 MB and 10 minutes.
• Up to 20 new URLs per day. The same URL is reused for 30 days without being fetched again.
• Media is fetched before anything is charged, so a bad URL costs nothing.

Webhooks

Pass webhookUrl (public https) on POST /v1/videos. We POST JSON { id, type, createdAt, data } where type is video.completed or video.failed and data is the same video object GET /v1/videos/{id} returns. Answer with any 2xx. A failed delivery is retried 3 times.

Every delivery is signed: X-GhostShorts-Signature: t=<unix>,v1=<hex>, where v1 is HMAC-SHA256 over "<t>.<body>"keyed with your account's signing secret (webhooks.signingSecret on GET /v1/me, without its whsec_ prefix). In Node:

const crypto = require('crypto');
// rawBody: the request body as received (string), before JSON.parse
function verifyGhostShorts(rawBody, header, signingSecret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto.createHmac('sha256', signingSecret.replace(/^whsec_/, '')).update(parts.t + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && expected.length === (parts.v1 || '').length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Rate limits and idempotency

• 60 requests per minute per account, of which 10 may create videos.
• Estimates, scripts and previews: 30 per hour and 100 per day.
• 3 videos in progress at once per account.
• 20 new media URLs per day.
• The public reference (templates, options, OpenAPI): 60 per minute per IP address.

Your current limits are on GET /v1/me under limits, and each response carries X-RateLimit-* headers. A 429 carries Retry-After.

Send an Idempotency-Key header on every POST, so a retry after a timeout never makes a second video. For 24 hours:

• Same key, same body: the first answer is replayed with Idempotent-Replayed: true. For POST /v1/videos the replay shows the video as it is now, with its current status and download link. Nothing is created or charged twice.
• Same key, different body: 422 IDEMPOTENCY_KEY_REUSED.
• Same key while the first request is still running: 409 IDEMPOTENCY_IN_PROGRESS.

Errors

Errors are RFC 9457 problem JSON (application/problem+json): { type, title, status, detail, code }, plus an errors array on INVALID_INPUT and upsell + plansUrl on every 402. Branch on code.

Video failure codes

When a video ends as failed or cancelled, error.code on the video (and in the video.failed webhook) is one of these. error.message always says what happened.

OpenAPI

The full OpenAPI 3.1 document, with every endpoint and schema, is at api.ghostshorts.com/v1/openapi.json. No key needed.

For agents

Stable plain-text URLs an agent can fetch directly. No key needed; they are generated from the API's own template registry, so they always match what the API accepts.

• https://api.ghostshorts.com/v1/llms.txt The whole API in one plain-text guide.
• https://api.ghostshorts.com/v1/templates/reddit_story.txt Reddit Story: inputs, a full example, credits, errors.
• https://api.ghostshorts.com/v1/templates/fake_text_message.txt Text Messages: inputs, a full example, credits, errors.
• https://api.ghostshorts.com/v1/templates/quiz_video.txt AI Quiz Video: inputs, a full example, credits, errors.
• https://api.ghostshorts.com/v1/templates/article_video.txt Article to Video: inputs, a full example, credits, errors.
• https://ghostshorts.com/developers/llms.txt The same guide, served from this site.