AI captions

Reelspan can write the captions for you: a YouTube title, description and tags, an Instagram caption, an X post, and so on, each in that network's style and within its limits. It works from what the post has: the video's frames and speech, the photos, or a caption you wrote.

There are three calls:

Each successful call uses one AI credit. Nothing is posted: you get the captions back and send them with your post.

From a video

curl -X POST https://api.reelspan.com/v1/ai/video-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -F "[email protected]" \
  -F "platforms=youtube,tiktok,instagram" \
  -F "context=Our new app launches on Monday; free for the first month"

import { Reelspan } from 'reelspan';
import { readFile } from 'node:fs/promises';

const reelspan = new Reelspan();
const captions = await reelspan.ai.captionsFromVideo(
  { data: await readFile('launch.mp4'), name: 'launch.mp4', type: 'video/mp4' },
  { platforms: ['youtube', 'tiktok', 'instagram'], context: 'Our new app launches on Monday; free for the first month' },
);

from reelspan import Reelspan

reelspan = Reelspan()
captions = reelspan.ai.captions_from_video(
    "launch.mp4",
    platforms=["youtube", "tiktok", "instagram"],
    context="Our new app launches on Monday; free for the first month",
)

Reelspan samples frames from the video and transcribes its speech, then writes the captions. The video can be a file or a public https link (Google Drive and Dropbox share links work), up to 100 MB and 5 minutes long. It is deleted once the captions are written; to post it, upload it separately.

• platforms: comma-separated; youtube,instagram,tiktok when left out.
• language: the language to write in, such as English or es. Without it, the captions follow the language spoken or written in the video.
• context: your notes on the video (facts, names, the angle you want), up to 4,000 characters. The AI is told to use only what the video and your notes show, and not to invent facts.

{
  "success": true,
  "ai_generated": true,
  "remaining_analyses": 99,
  "youtube": {
    "title": "Our new app launches Monday: first month free #shorts",
    "description": "Our new app launches on Monday, and the first month is free…",
    "tags": ["app launch", "new app", "productivity app"]
  },
  "tiktok": { "caption": "New app drops Monday. First month on us. #applaunch #productivity #newapp" },
  "instagram": { "caption": "Our new app launches Monday.\n\nTry it free for the first month…" }
}

remaining_analyses is how many AI credits are left this month.

From an upload, photos or your text

adapt-captions writes from whatever you give it. The most common case is media you already uploaded with Upload media: send its media_id, and Reelspan reads the frames and speech on the server.

curl -X POST https://api.reelspan.com/v1/ai/adapt-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "med_4f2a…", "platforms": ["youtube", "linkedin", "x"], "notes": "Behind the scenes of our launch week"}'

const captions = await reelspan.ai.writeCaptions({ mediaId: 'med_4f2a…', platforms: ['youtube', 'linkedin', 'x'], notes: 'Behind the scenes of our launch week' });

captions = reelspan.ai.write_captions(media_id="med_4f2a…", platforms=["youtube", "linkedin", "x"], notes="Behind the scenes of our launch week")

Give it any of these (at least one):

• text: your own caption, up to 5,000 characters. It is kept as the facts and adapted per network. With text, the video's speech isn't transcribed.
• notes: hints for the AI without writing the caption yourself, up to 4,000 characters.
• media_id: a video uploaded earlier.
• photo_media_ids: up to 10 photos uploaded earlier.
• frames, images and audio: the media itself, base64-encoded, if you'd rather not upload it first. See the fields below.

kind (video, photo or text) says what the post is, and language sets the language. The answer is like the one above, plus summary (one or two neutral sentences about the post, useful as a base caption) and transcript when the speech was transcribed.

With nothing to work from, the answer is 400 NOTHING_TO_ADAPT.

Rewrite your captions

rewrite-captions keeps your facts and changes the style, length and hashtags for each network.

curl -X POST https://api.reelspan.com/v1/ai/rewrite-captions \
  -H "Authorization: Bearer $REELSPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "youtube": { "title": "How we ship a release in one day", "description": "A walk through our release checklist." } },
    "platforms": ["linkedin", "x", "threads"],
    "instructions": "Friendly, no emojis"
  }'

const captions = await reelspan.ai.rewriteCaptions(
  { youtube: { title: 'How we ship a release in one day', description: 'A walk through our release checklist.' } },
  { platforms: ['linkedin', 'x', 'threads'], instructions: 'Friendly, no emojis' },
);

captions = reelspan.ai.rewrite_captions(
    {"youtube": {"title": "How we ship a release in one day", "description": "A walk through our release checklist."}},
    platforms=["linkedin", "x", "threads"],
    instructions="Friendly, no emojis",
)

• content: your captions, keyed by network, up to 20,000 characters in all.
• platforms: the networks to write for. Without it, the supported networks named in content.
• instructions: how to write them, up to 1,000 characters.

What you get per network

Captions are cut to fit each network's limit, at a word where possible.

These nine networks are the ones AI captions support; any other network in platforms answers 400. To post them, put each value in that network's caption field, for example youtube_title and youtube_description on Post a video.

Credits per plan

Credits renew on the first day of each month (UTC) and don't carry over. A credit is used only when captions come back; a call that fails costs nothing. Calls made with a test key use real credits too.

Errors

All three calls need a key with the publish scope.