Every option, with its limits and defaults, is in the full guide below and at api.ghostshorts.com/v1/templates.
1. Check it first. POST /v1/scripts writes the questions for 0 credits and returns them, so you can check them before you make the video. POST /v1/estimate with the same body returns the cost without spending anything.
2. Create the video. One request; the answer is a video id, and 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' \
-d '{
"template": "quiz_video",
"inputs": {
"topic": "world capitals",
"difficulty": "medium",
"questionCount": 5
}
}'3. Get the MP4. Poll GET /v1/videos/{id} or pass webhookUrl. It usually takes about a minute; the downloadUrl works for 7 days.
From an AI assistant, connect the MCP server (https://api.ghostshorts.com/mcp) and ask for a quiz video: it calls create_video with template quiz_video for you.
Each video uses one video from your plan's monthly allowance, and AI narration is included on current plans within fair use. There is no separate API plan. See plans.
Every input, a complete example request and response, credits, errors and timing, generated from the API itself. Paste it into any AI chat and it knows how to make this video.
# GhostShorts API: AI Quiz Video (quiz_video)
A multiple-choice quiz short: question card, countdown, answer reveal with a fact line, narrated, over a looping background.
Output: one 1080x1920 (9:16) MP4.
This guide: https://api.ghostshorts.com/v1/templates/quiz_video.txt All templates: https://api.ghostshorts.com/v1/llms.txt
## Base URL and auth
Base URL: https://api.ghostshorts.com
Auth: send your API key on every request as the header "Authorization: Bearer gs_live_..."
Create a key at https://ghostshorts.com/app/settings/api-keys (the key is shown once). Keys use your plan's videos and credits; there is no separate API plan. Plans: https://ghostshorts.com/pricing
## Flow
1. Optional and free: POST /v1/estimate with the same {"template", "inputs"} body returns the cost without spending anything.
2. Optional and free (0 credits): POST /v1/scripts with {"template": "quiz_video", "inputs": {...}} writes the question pack and returns it with a "projectId". Check it, then send that projectId on POST /v1/videos so it is reused instead of written again.
3. POST /v1/videos with {"template": "quiz_video", "inputs": {...}} (optional "webhookUrl", optional "projectId" from the free step). It answers 202 with the video object; keep its "id".
4. Poll GET /v1/videos/{id} every 10-20 s until "status" is "completed" or "failed" (or "cancelled" if you cancelled it). In between you may see queued, preparing_media, generating_script, narrating and rendering. A queued video can be cancelled with POST /v1/videos/{id}/cancel.
5. On "completed", "downloadUrl" is a public link (no key needed) valid for 7 days. Give it to the user exactly as returned. On "failed", "error" is { code, message }.
6. Iterating: to change a finished video, POST /v1/videos again with its "projectId". Renders 2 and 3 of a project are included (no video used); render 4 counts again. Leaving projectId out starts a new project and uses a new video. One video per project at a time. Send the full inputs again (the new version is applied).
Webhook (optional): pass "webhookUrl" (public https) and we POST { id, type, createdAt, data } to it, where type is video.completed or video.failed and data is the video object. Deliveries carry the header X-GhostShorts-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with webhooks.signingSecret from GET /v1/me minus its whsec_ prefix. Verification code: https://api.ghostshorts.com/v1/llms.txt
Idempotency: send an "Idempotency-Key" header (any unique string up to 255 characters) on every POST. Retrying with the same key and body within 24 hours replays the first answer, so nothing is created or charged twice. Only a success is kept: after a refusal (400, 402, ...) fix the request and resend it with the same key.
Several at once: POST /v1/videos/batch with {"items": [ {template, inputs, projectId?, webhookUrl?}, ... ]} (1 to 10). If the whole batch does not fit the allowance nothing is created. Video responses carry "account" { videosLeft, narrationsLeft, aiCreditsLeft, resetsAt }.
## Use this template from MCP
From an MCP client (https://api.ghostshorts.com/mcp, same API key): estimate_cost, generate_script, then create_video with template "quiz_video" and these inputs; poll get_video until completed. To change the video, call create_video again with its projectId (renders 2-3 of a project are free). create_videos queues up to 10 at once.
## Prefilled web link
To hand a person the template in the browser instead: https://ghostshorts.com/quiz-video-maker?topic=<url-encoded topic>
The page opens with that input loaded and shows a free preview before any payment.
## Inputs (the "inputs" object for template "quiz_video")
Fields marked optional may be omitted; the default shown is applied. Unknown fields are refused with 400 INVALID_INPUT.
- topic (string, required, 2-200 chars): What the quiz is about, e.g. "the Roman Empire".
- difficulty (string, optional, default medium, one of [easy, medium, hard])
- questionCount (number, optional, default 5, one of [5, 7, 10])
- categoryId (string, optional, one of [general-knowledge, geography, history, science, movies-tv, music, sports, food-drink, video-games, logos-brands]): Optional steer for the generator.
- videoTitle (string, optional, 1-48 chars): Title on the intro card.
- voiceId (string, optional, default LcfcDJNUP1GQjkzn1xUU, one of [LcfcDJNUP1GQjkzn1xUU, EXAVITQu4vr4xnSDxMaL, pNInz6obpgDQGcFmaJgB, TxGEqnHWrfWFTfGW9XjX, JBFqnCBsd6RMkjVDRZzb, onwK4e9ZLuTAKqWW03F9]): Narrator voice. See GET /v1/options voices tagged quiz_video.
- theme (string, optional, default neon, one of [neon, sunset, classic])
- font (string, optional, default anton, one of [anton, bangers, bebas-neue, poppins])
- countdownSeconds (number, optional, default 5, one of [3, 5, 7])
- captionsEnabled (boolean, optional, default false)
- silent (boolean, optional, default false): Render with no narration. Refused unless explicitly true.
## Example request
Set GS_KEY to your key first (export GS_KEY=gs_live_...).
curl -X POST https://api.ghostshorts.com/v1/videos \
-H "Authorization: Bearer $GS_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quiz-video-example-001" \
--data-binary @- <<'JSON'
{
"template": "quiz_video",
"inputs": {
"topic": "The Roman Empire",
"difficulty": "medium",
"questionCount": 5,
"videoTitle": "Roman Empire Quiz",
"theme": "neon"
}
}
JSON
Response: 202 Accepted, header Location: /v1/videos/cmuhb7qk2000408l4c1dv5n8p
{
"id": "cmuhb7qk2000408l4c1dv5n8p",
"template": "quiz_video",
"status": "queued",
"stage": "Queued",
"progress": null,
"projectId": null,
"exportId": null,
"downloadUrl": null,
"downloadExpiresAt": null,
"error": null,
"creditsCharged": null,
"estimatedSecondsRemaining": 90,
"createdAt": "2026-09-24T15:00:00.000Z",
"completedAt": null,
"cutAtMs": null,
"notices": [
"Answers are AI-generated. Check the facts before you publish; you are the one whose channel says it."
]
}
Once completed, GET /v1/videos/cmuhb7qk2000408l4c1dv5n8p answers (example values):
{
"id": "cmuhb7qk2000408l4c1dv5n8p",
"template": "quiz_video",
"status": "completed",
"stage": "Done",
"progress": 100,
"projectId": "cmuhb7qkb000508l4h6tz2w4r",
"exportId": "cmuhb8f1m000608l4e0xs9k3u",
"downloadUrl": "https://api.ghostshorts.com/v1/d/pT6vJ1cW9xE4kQ7nB2yH5rL8mD3fA0sGuZiOeVqNwKj",
"downloadExpiresAt": "2026-10-01T15:01:12.000Z",
"error": null,
"creditsCharged": {
"narration": 0,
"render": 0,
"videos": 1
},
"estimatedSecondsRemaining": null,
"createdAt": "2026-09-24T15:00:00.000Z",
"completedAt": "2026-09-24T15:01:12.000Z",
"cutAtMs": null,
"notices": [
"Answers are AI-generated. Check the facts before you publish; you are the one whose channel says it."
]
}
## Credits
- narration: 1 credit per minute of narration across the whole pack (legacy plans); included on current plans within fair use
- render: 1 video from the monthly allowance (current plans); export counter on legacy plans
Plan and balance are checked before anything runs, so a 402 refusal costs nothing. creditsCharged on the video says what was actually charged.
## Notes
- Get the pack free first with POST /v1/scripts (template quiz_video), check the answers, then pass its projectId to POST /v1/videos.
- Questions are AI-generated. Check answers before publishing, especially dates and award years.
- Topics that target a group of people are refused.
## Errors
Errors are JSON with Content-Type application/problem+json: { type, title, status, detail, code }. Branch on "code". 400 INVALID_INPUT adds "errors": [{ path, message, code }]. Every 402 adds "upsell" and "plansUrl" (https://ghostshorts.com/pricing). A 429 carries Retry-After. Full reference: https://ghostshorts.com/developers/errors
- 401 MISSING_API_KEY: No Authorization: Bearer header was sent.
- 401 INVALID_API_KEY: The key is unknown or has been revoked. Create a new one in Settings.
- 402 SUBSCRIPTION_REQUIRED: This step needs an active plan. The response carries plansUrl.
- 402 INSUFFICIENT_CREDITS: Not enough credits for this step. Top up or wait for your plan to renew.
- 402 VIDEO_ALLOWANCE_EXHAUSTED: This month's video allowance is used up.
- 402 SOFT_CAP_REACHED: A fair-use limit for this period was reached.
- 402 VOICE_FAIR_USE_REACHED: This month's voice allowance is used. Videos already started can still be finished; new narrations start again at the next renewal, or move up a plan.
- 400 VIDEO_TOO_LONG: Videos can be up to 10 minutes. Split this one into parts. Also the error.code of a video whose finished length came out over 10 minutes.
- 400 INVALID_INPUT: The body does not match the schema. The errors array names each field. Also sent as 413 for a body over 2 MB.
- 400 INVALID_WEBHOOK_URL: webhookUrl must be a public https URL.
- 404 NOT_FOUND: No such endpoint, or no such video, project or download link on this account.
- 409 IDEMPOTENCY_IN_PROGRESS: A request with this Idempotency-Key is still running. Retry after Retry-After.
- 422 IDEMPOTENCY_KEY_REUSED: This Idempotency-Key was already used with a different body. Use a new key for a new request.
- 429 RATE_LIMITED: Too many requests. Wait for Retry-After seconds.
- 429 CONCURRENCY_LIMIT: Three videos are already in progress on this account. Retry after one finishes.
- 503 SERVICE_UNAVAILABLE: The video queue is briefly unavailable. Nothing was charged; retry shortly.
- 400 NARRATION_REQUIRED: The video cannot be rendered without narration.
- 400 SAFETY_REJECTED: The content was refused by our safety checks. Change the topic or text.
A video that fails has "status": "failed" and "error": { code, message }; error.message always says what happened. Codes for this template:
- BACKGROUND_UNAVAILABLE: The background video or category you picked has no usable footage. Pick one from GET /v1/options.
- PACK_FAILED: The quiz questions could not be written.
- NARRATION_FAILED: The narration could not be recorded.
- RENDER_FAILED: The render failed. Create the video again.
- INTERRUPTED: Processing was interrupted. Create the video again; contact support if narration was charged.
- CANCELLED: You cancelled the video while it was queued.
## Timing
Renders usually take about a minute; own-media imports add about 30 seconds the first time; the first attempt occasionally takes several minutes before the automatic retry succeeds.
Machine-readable: https://api.ghostshorts.com/v1/openapi.json Templates: https://api.ghostshorts.com/v1/templates Options (voices, backgrounds, music, caption presets): https://api.ghostshorts.com/v1/options
Create a key, send one request, get an MP4 back in about a minute.