Browse the docs

Create Reddit story video

Makes a Reddit story video: a post card read out by a voice, then the story with captions, over gameplay. Give title and body (your story), or prompt (the story is written for you, free). Spends minutes, not credits: voiceover and caption minutes for the narration (about 1 of each per minute of story). By default it makes an editable draft and the job output has 4 stills, a 7-day previewUrl and editorUrl; restyle it with update_video, then render_video. "render": true renders the MP4 straight away (export minutes for the video length). Run estimate_cost (or dryRun: true) first and confirm the cost. Takes a minute or two: wait with get_job (waitSeconds). At most 3 videos are made at once.

Or open inClaude Code Codex Cursor Claude ChatGPT

Paste it into any AI assistant. The shortcuts open with the prompt typed in; nothing is sent until you press enter.

At a glance

Property	Value
REST	`POST https://api.clippie.ai/v1/videos/reddit-story`
MCP tool	`create_reddit_video`
Scope	`create`
Cost	Spends credits or minutes, at the same prices as the app. Send `"dryRun": true` (or call estimate_cost) first to see the exact cost without spending anything.
Limit bucket	`voiceover` (see Rate limits)

REST
POST https://api.clippie.ai/v1/videos/reddit-story
MCP tool
create_reddit_video
Scope
create
Cost
Spends credits or minutes, at the same prices as the app. Send "dryRun": true (or call estimate_cost) first to see the exact cost without spending anything.
Limit bucket
voiceover (see Rate limits)

Parameters

Name	In	Type	Required	Description
`title`	body	string	No	The post title, read out over the card first. Give title and body, or prompt (title optional). 1-300 chars.
`body`	body	string	No	The story, read out after the title with captions. 20-9000 chars.
`prompt`	body	string	No	What the story is about: the story is written for you (free), its first line becoming the title unless you give one. 3-2000 chars.
`durationSeconds`	body	integer	No	Narration length to write a prompt story for, 30-300 seconds (default 60). 30-300.
`voiceId`	body	string	No	Narration voice id from list_voices (Clippie voices or your cloned ones). Defaults to your brand voice. 1-64 chars.
`language`	body	string	No	Narration and caption language code from list_languages (e.g. "en", "es"). Default: detected. Up to 10 chars.
`playbackRate`	body	number	No	Narration speed, 1-2 (default 1). Faster is shorter. 1-2.
`backgroundVideoId`	body	string	No	Background clip id from list_background_videos. Up to 80 chars.
`backgroundGenre`	body	string	No	A list_background_videos category (e.g. "minecraft"): picks a clip from it. Default: the editor's GTA clip. Up to 60 chars.
`musicId`	body	string	No	Background music id from list_music, or "none". Defaults to your brand track. Up to 80 chars.
`musicVolume`	body	number	No	Music volume 0-100. The editor starts at 1 (just under the voice). 0-100.
`captionStyleId`	body	integer	No	Caption style id from list_caption_styles. Defaults to your brand caption style. 1-17.
`captionPosition`	body	number	No	Vertical caption position, 0 (top) to 100 (bottom). Default 50. 0-100.
`captionSize`	body	number	No	Caption size, 0-100. Default 50. 0-100.
`textStyle`	body	object	No	Colour, case, outline and shadow over the caption style.
`ratio`	body	string	No	Frame shape. Default 9:16. One of `9:16`, `16:9`.
`card`	body	object	No	The Reddit post card shown while the title is read.
`render`	body	boolean	No	Default false: make an editable draft and return stills and a preview link (no export minutes). true: render the MP4 straight away (spends export minutes).
`dryRun`	body	boolean	No	Check the request and return { estimate } (credits and minutes) without spending anything.
`webhookUrl`	body	string (URL)	No	https URL that receives job.completed / job.failed, signed with your webhook secret. Up to 2048 chars.
`Idempotency-Key`	header	string	No	Retry-safe key: a retry with the same key and body within 24 hours returns the first job instead of starting (and charging) again. The same key with a different body is a 409. MCP clients pass it as the idempotencyKey argument. 1-255 chars. MCP: `idempotencyKey`.

title
In:
body
Type:
string
Required:
No
Description:
The post title, read out over the card first. Give title and body, or prompt (title optional). 1-300 chars.
body
In:
body
Type:
string
Required:
No
Description:
The story, read out after the title with captions. 20-9000 chars.
prompt
In:
body
Type:
string
Required:
No
Description:
What the story is about: the story is written for you (free), its first line becoming the title unless you give one. 3-2000 chars.
durationSeconds
In:
body
Type:
integer
Required:
No
Description:
Narration length to write a prompt story for, 30-300 seconds (default 60). 30-300.
voiceId
In:
body
Type:
string
Required:
No
Description:
Narration voice id from list_voices (Clippie voices or your cloned ones). Defaults to your brand voice. 1-64 chars.
language
In:
body
Type:
string
Required:
No
Description:
Narration and caption language code from list_languages (e.g. "en", "es"). Default: detected. Up to 10 chars.
playbackRate
In:
body
Type:
number
Required:
No
Description:
Narration speed, 1-2 (default 1). Faster is shorter. 1-2.
backgroundVideoId
In:
body
Type:
string
Required:
No
Description:
Background clip id from list_background_videos. Up to 80 chars.
backgroundGenre
In:
body
Type:
string
Required:
No
Description:
A list_background_videos category (e.g. "minecraft"): picks a clip from it. Default: the editor's GTA clip. Up to 60 chars.
musicId
In:
body
Type:
string
Required:
No
Description:
Background music id from list_music, or "none". Defaults to your brand track. Up to 80 chars.
musicVolume
In:
body
Type:
number
Required:
No
Description:
Music volume 0-100. The editor starts at 1 (just under the voice). 0-100.
captionStyleId
In:
body
Type:
integer
Required:
No
Description:
Caption style id from list_caption_styles. Defaults to your brand caption style. 1-17.
captionPosition
In:
body
Type:
number
Required:
No
Description:
Vertical caption position, 0 (top) to 100 (bottom). Default 50. 0-100.
captionSize
In:
body
Type:
number
Required:
No
Description:
Caption size, 0-100. Default 50. 0-100.
textStyle
In:
body
Type:
object
Required:
No
Description:
Colour, case, outline and shadow over the caption style.
ratio
In:
body
Type:
string
Required:
No
Description:
Frame shape. Default 9:16. One of 9:16, 16:9.
card
In:
body
Type:
object
Required:
No
Description:
The Reddit post card shown while the title is read.
render
In:
body
Type:
boolean
Required:
No
Description:
Default false: make an editable draft and return stills and a preview link (no export minutes). true: render the MP4 straight away (spends export minutes).
dryRun
In:
body
Type:
boolean
Required:
No
Description:
Check the request and return { estimate } (credits and minutes) without spending anything.
webhookUrl
In:
body
Type:
string (URL)
Required:
No
Description:
https URL that receives job.completed / job.failed, signed with your webhook secret. Up to 2048 chars.
Idempotency-Key
In:
header
Type:
string
Required:
No
Description:
Retry-safe key: a retry with the same key and body within 24 hours returns the first job instead of starting (and charging) again. The same key with a different body is a 409. MCP clients pass it as the idempotencyKey argument. 1-255 chars. MCP: idempotencyKey.

Example

curl

# 1. Dry run: the exact cost, nothing is spent.
curl https://api.clippie.ai/v1/videos/reddit-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dryRun": true
  }'
# => { "dryRun": true, "estimate": { "credits": ..., "minutes": { ... }, "wouldSucceed": true } }

# 2. The real call. Keep the key and send the same one if you retry, so it is never charged twice.
KEY=$(uuidgen)
curl https://api.clippie.ai/v1/videos/reddit-story \
  -H "Authorization: Bearer $CLIPPIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{}'
# => 202 { "job": { "id": "job_...", "status": "queued", ... } }

create-reddit-video.mjs

import { randomUUID } from 'node:crypto';

const auth = { Authorization: `Bearer ${process.env.CLIPPIE_API_KEY}` };

const input = {};

async function call(body, headers = {}) {
  const res = await fetch('https://api.clippie.ai/v1/videos/reddit-story', {
    method: 'POST',
    headers: { ...auth, 'Content-Type': 'application/json', ...headers },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${json.error.type}: ${json.error.message}`);
  return json;
}

// 1. Dry run: the exact cost, nothing is spent. Confirm it before going on.
const { estimate } = await call({ ...input, dryRun: true });
console.log(estimate); // { credits, minutes, wouldSucceed, reason }

// 2. Create. Keep the key and reuse it on retries, so a retry never charges twice.
let { job } = await call(input, { 'Idempotency-Key': randomUUID() });

// 3. Wait. Each call holds for up to 30 seconds until the job changes.
while (!['completed', 'failed', 'canceled'].includes(job.status)) {
  const res = await fetch(`https://api.clippie.ai/v1/jobs/${job.id}?wait=30`, { headers: auth });
  ({ job } = await res.json());
}
console.log(job.status, job.output);

Response

202 { job }: the job, straight away. Wait for it with Get job (?wait=30) or a webhookUrl; see Jobs and waiting. With "dryRun": true the answer is 200 { dryRun: true, estimate } and nothing is started.

202 Accepted

{
  "job": {
    "id": "job_abc123",
    "object": "job",
    "kind": "create_reddit_video",
    "status": "queued",
    "step": null,
    "progress": null,
    "input": {
      "prompt": "The lost library of Alexandria"
    },
    "output": null,
    "cost": {
      "credits": 0,
      "minutes": {
        "voiceover": 1,
        "captions": 1,
        "export": 1
      }
    },
    "error": null,
    "source": "api",
    "webhookUrl": null,
    "createdAt": "2026-10-24T12:00:00.000Z",
    "startedAt": null,
    "completedAt": null
  }
}

Dry run (200), shape only

{
  "dryRun": true,
  "estimate": {
    "credits": 0,
    "minutes": {
      "voiceover": 0,
      "captions": 0,
      "export": 0
    },
    "wouldSucceed": true
  }
}

From an MCP client

Your AI calls create_reddit_video with the same fields as JSON arguments, plus idempotencyKey instead of the header. See MCP server to connect one.

tools/call

{
  "name": "create_reddit_video",
  "arguments": {
    "idempotencyKey": "a-unique-key-per-thing-you-make"
  }
}