instagram-reels
Build and run an automated Instagram Reels pipeline on Kortix: topic and fact check, hook-first script, text-to-speech narration with word timestamps (ElevenLabs, or Sarvam Bulbul for Indian languages
SKILL.mdpackages/starter/templates/marketplace/skills/instagram-reels/SKILL.md
GitHubInstagram Reels
Turns a topic into a finished, checked Reel and publishes it to an Instagram Business or Creator account through the Kortix Instagram connector. It works for one Reel made in a session, and for a schedule that runs with nobody watching.
topic -> source + fact ledger -> script -> voice + word timings -> shot list -> images
-> render 1080x1920 -> QA + frame review -> caption + cover -> publish (container, poll, publish) -> ledger
The helpers are in scripts/. Copy the folder into the project (skills/instagram-reels/scripts/).
| Script | Does |
|---|---|
tts.py |
ElevenLabs narration, one request per sentence, exact word timings |
image.py |
gpt-image-2 (OpenAI) or Nano Banana (Gemini) images, with a cost log |
render_short.py |
Stills + voice + words -> 1080x1920 30 fps H.264/AAC: motion, karaoke captions, headlines, ducked music, -14 LUFS |
qa.py |
Machine checks plus one frame per second for review |
ig_publish.py |
Reel / story / post / carousel publishing with live-feed dedupe and a ledger |
kx.py |
Connector calls, 1-hour public file links, ledger helpers |
0. Setup (once per project)
- Account. The Instagram account must be a Business or Creator account (Settings -> Account type). Personal accounts can't publish through the API.
- Brand facts. Ask about the niche, audience, language, tone, voice, visual style, colours, fonts, cadence, hashtag set, and whether posts need a person's approval. Save them to
memory/or abrand.md. - Voice provider. Ask the user to choose before you request any key: ElevenLabs (exact word timings from
tts.py, the widest voice range, audio tags on v3) or Sarvam Bulbul (Hindi, Bengali, Tamil, Telugu, Gujarati, Kannada, Malayalam, Marathi, Punjabi, Odia and Indian English, at under half the price). Record the choice inmemory/orbrand.mdand request only that provider's key. - Secrets (setup links, never chat):
kortix secrets request ELEVENLABS_API_KEY OPENAI_API_KEY --scope runtime # or GEMINI_API_KEY + IMAGE_PROVIDER=gemini # Sarvam Bulbul instead of ElevenLabs (Indian languages): kortix secrets request SARVAM_API_KEY --scope runtime - Instagram connector (Composio). Install it and hand over the sign-in link:
Lock it down inkortix connectors catalog install instagram --slug instagram kortix connectors connect instagram --owner project kortix connectors accounts instagram # if several accounts: export IG_ACCOUNT="<name>"kortix.yaml. Rules are first-match, so allows go before the block:
Check:connectors: - slug: instagram provider: composio app: instagram policies: - { match: post_ig_user_media, action: always_run } - { match: post_ig_user_media_publish, action: always_run } # require_approval = a person approves each post - { match: get_user_info, action: always_run } - { match: get_multiple_nodes, action: always_run } - { match: get_ig_user_content_publishing_limit, action: always_run } - { match: get_ig_media_insights, action: always_run } - { match: "*", action: block } # no DMs, no deleting, no commentspython3 scripts/ig_publish.py reel --media x.mp4 --key t --dry-runprints the IG user ID. Note: a heldrequire_approvalcall has to be approved while the run waits. For unattended schedules, preferalways_runplus a strict QA gate, or put the human gate earlier (a person moves a file fromreview/toqueue/). - Voice. ElevenLabs:
python3 scripts/tts.py --list-voices, pick one with the user, storeTTS_VOICE_ID. Sarvam: play the user a few Bulbul speakers (for exampleshubh,priya,aditya) in their language and store the one they pick.
1. Topic and facts
One idea per Reel. Keep a dedupe folder (state/covered/<slug>.json, one file per topic). Read the real source and write facts.json (claim, quote, URL, verdict) before writing narration. Only supported claims reach the voice, the screen or the caption. If the main claim fails, drop the topic.
2. Script for Reels
Target 15–45 s. Reels must be 5–90 s to publish as a Reel through the API (longer uploads become regular video posts). Short Reels get more completions and replays.
| Beat | Rule |
|---|---|
| Hook (0–1.5 s) | The first frame must stop the scroll: the subject plus a bold claim, number or question. Text on screen from frame 1, since many people watch muted. No intros, no logos. |
| Build | One idea per sentence, a new visual every 1.5–3 s, a concrete comparison. |
| Payoff | Answer the hook. End on a line that loops back to the start, or one clear call to action ("Save this for later", "Follow for part 2"). Only one ask. |
Tone and emotion. Choose an arc (curiosity -> reveal, problem -> fix, myth -> truth) and a register that matches the brand. Write for the ear. With ElevenLabs v3 (TTS_MODEL=eleven_v3), audio tags like [excited], [laughs] or [whispers] add emotion. Use one or two per Reel, not every line.
3. Voice
export TTS_VOICE_ID=<voice>
python3 scripts/tts.py script.txt work/ # narration.wav, words.json, sentences.json, sentence-N.wav
Sarvam Bulbul (bulbul:v3) is the alternative for Indian languages: Hindi, Bengali, Tamil, Telugu, Gujarati, Kannada, Malayalam, Marathi, Punjabi, Odia and Indian English. tts.py calls ElevenLabs only. Bulbul returns audio without word timings: voice each sentence through the Sarvam API, then get words.json from a speech-to-text pass with word timestamps on narration.wav before you render.
Re-voice one sentence at a time to fix a read. Shorten the script rather than speeding up the voice.
4. Images
shots.json: one shot per sentence, 1.5–3.5 s, a concrete subject and a composition for each. Sources: the brand's own asset library -> licensed photos with credits -> generated:
python3 scripts/image.py "<brand style prefix>, <subject + composition>, vertical, subject centred, no text" work/shot-01.png --aspect 9:16 --quality medium
(or the Kortix image_gen tool). Keep one fixed style prefix per brand. Ask for no text in the image, since the renderer adds it. Read every image and regenerate wrong ones. Cap attempts per Reel and per month.
Instagram safe zones (1080x1920): keep text and faces out of the top ~250 px and the bottom ~540 px (caption, buttons, audio label), and out of the right ~120 px (like/comment/share rail). The profile grid shows the centre 1080x1350 (4:5), so the cover's subject and title must fit there.
5. Render
python3 scripts/render_short.py work/render.json
{"shots": [{"image": "work/shot-01.png", "duration": 2.2, "motion": "in", "headline": "YOU'RE DOING THIS WRONG"},
{"image": "work/shot-02.png", "duration": 2.8, "motion": "right"}],
"narration": "work/narration.wav", "words": "work/words.json",
"music": "assets/licensed-bed.mp3", "music_db": -22, "caption_y": 1380, "out": "out/reel.mp4"}
Captions sit at y≈1380, above the bottom UI. Headlines sit at y≈330, below the top UI. Music must be licensed for commercial use: API-published Reels can't attach Instagram's music library, so a business account must bring its own rights.
Cover: render a 1080x1920 JPEG with the title inside the centre 4:5 area (the instagram-content-studio skill's card.py does this), or pick a frame.
6. QA gate
python3 scripts/qa.py out/reel.mp4 --max 90 --frames out/qa-frames
The machine checks must all pass (1080x1920, H.264 yuv420p, AAC, 5–90 s, -16 to -12 LUFS, peak ≤ -1 dBFS, no dead air, faststart). Then open every frame and write review.md: hook frame readable muted? Right subject in each shot? Numbers match the facts? Text clear of the safe zones? Score hook / accuracy / visuals / captions / audio 0–10. Below 8 means fix and re-check (max 3 rounds). Never pass a Reel without reading the frames.
7. Caption
- First line = the hook, under ~125 chars (only that shows before "more").
- 2–4 short lines of value or context. Sources if it's factual.
- One call to action. AI disclosure where visuals or voice are generated ("Voice and visuals are AI-generated.").
- 3–5 relevant hashtags (more doesn't help). Max 2,200 chars and 30 hashtags. Write
#as is; the connector handles encoding. - Instagram applies its own "AI info" label to some content. Honest disclosure in the caption is still the safe default.
8. Publish
python3 scripts/ig_publish.py reel --media out/reel.mp4 --caption-file out/caption.txt --cover out/cover.jpg \
--key reel-2026-10-30-why-saturn-is-flat --ledger-dir state/published
How it works: the MP4 gets a 1-hour Kortix session link -> post_ig_user_media (media_type: REELS, video_url, caption, share_to_feed: true, optional cover_url) -> poll status_code every 10 s until FINISHED (up to 10 min) -> post_ig_user_media_publish -> permalink -> ledger file -> link revoked.
- Duplicate safety: the ledger key and the live feed (first 80 normalised caption characters) are checked before any write, and again after an ambiguous publish error. A post that went through is recorded, never posted twice. Make every caption unique.
- Limits: 100 API-published posts per 24 h per account (
get_ig_user_content_publishing_limit). For a healthy feed, space Reels at least an hour apart. - Errors:
9007/ not ready means the container wasn'tFINISHED: keep polling. ContainerERRORmeans the file is out of spec: rerun QA. Auth errors mean reconnect the connector (kortix connectors connect instagram). Allow 3 attempts per Reel, then mark it failed for a person.
9. Automate on Kortix
Two agents: a producer (voice and image keys, no Instagram connector) writes passed Reels into queue/, and a publisher (Instagram connector only) posts the oldest one.
agents:
reels-producer:
prompt_file: agents/reels-producer.md # load skills/instagram-reels; steps 1-7; write to queue/<slug>/; never publish
skills: [instagram-reels]
secrets: [ELEVENLABS_API_KEY, OPENAI_API_KEY] # SARVAM_API_KEY instead of ELEVENLABS_API_KEY when the user chose Sarvam
connectors: []
reels-publisher:
prompt_file: agents/reels-publisher.md # load the skill; publish the oldest passed item with step 8; report the permalink
skills: [instagram-reels]
connectors: [instagram]
triggers:
- { slug: make-reel, type: cron, agent: reels-producer, cron: "0 0 6 * * *", timezone: UTC, enabled: false, overlap: allow }
- { slug: publish-reel, type: cron, agent: reels-publisher, cron: "0 0 17 * * *", timezone: UTC, enabled: false, overlap: allow }
Store finished media and ledgers on the project Drive (/drives/<folder>/) or S3/R2, since /workspace doesn't survive the session. Use one folder per Reel and one ledger file per post. Ship triggers disabled and enable them after the user approves 2–3 Reels made by hand. Post when the audience is active (the account's insights show the hours).
Costs (per 30 s Reel, list prices, October 2026)
| Item | Cost |
|---|---|
| ElevenLabs TTS, |
~$0.05–0.10 |
or Sarvam Bulbul TTS, same chars (₹30 per 10k chars on bulbul:v3, ~$0.035 per 1k) |
~$0.02–0.03 |
| 6–10 images, gpt-image-2 medium ( |
~$0.25–0.50 |
| Render, QA, Instagram Graph API | $0 |
| Agent model tokens | largest variable: check Kortix usage |
Hard rules
- Never publish a Reel that failed QA or skipped the frame review.
- Never invent facts. Licensed music and images only. Disclose AI-generated voice and visuals.
- Never DM, comment, delete or edit posts unless the user asked for it. The connector policy should block these anyway.