Build a Narrated Video

An end-to-end walkthrough that writes a script with an LLM, generates clips, synthesizes a voiceover, and combines them — using one API key.

This tutorial chains three model types in one script: a language model writes the narration, a video model generates the footage, and a speech model reads the script aloud. It is a realistic example of why a single API and balance across model types is useful.

What you need: Python 3.9+, an API key, and ffmpeg if you want to mux the audio and video at the end.

This runs real generation jobs and costs real credits. Video is the expensive part — start with a short duration while you are iterating, and use the pricing estimate if you want an exact figure first.

Setup

pip install requests
export ATLASCLOUD_API_KEY="your-api-key"

Step 1 — Shared helpers

Every media job follows the same submit-then-poll shape, so define it once.

import os, time, requests

API_KEY = os.environ["ATLASCLOUD_API_KEY"]
BASE = "https://api.atlascloud.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
TERMINAL = {"completed", "succeeded", "failed", "timeout"}


def submit(endpoint: str, model: str, **params) -> str:
    """Submit a job. Parameters are flat — do not wrap them in an `input` object."""
    r = requests.post(f"{BASE}/model/{endpoint}",
                      headers=HEADERS, json={"model": model, **params}, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["id"]


def wait(prediction_id: str, timeout: int = 900) -> dict:
    """Poll until terminal, backing off as it goes."""
    deadline, delay = time.time() + timeout, 2.0
    while time.time() < deadline:
        r = requests.get(f"{BASE}/model/prediction/{prediction_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()["data"]
        if data.get("status") in TERMINAL:
            if data["status"] in ("failed", "timeout"):
                raise RuntimeError(f"Job failed: {data.get('error') or data['status']}")
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)
    raise TimeoutError(prediction_id)


def download(url: str, path: str) -> str:
    r = requests.get(url, timeout=300)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

Step 2 — Write the script with an LLM

Language models use a different base URL and are synchronous, so they do not go through submit/wait.

def write_narration(topic: str) -> str:
    r = requests.post(
        "https://api.atlascloud.ai/v1/chat/completions",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "model": "deepseek-ai/deepseek-v3.2",
            "messages": [
                {"role": "system",
                 "content": "You write narration for short videos. "
                            "Reply with two sentences of spoken narration and nothing else."},
                {"role": "user", "content": f"Topic: {topic}"},
            ],
            "max_tokens": 200,
        },
        timeout=120,
    )
    r.raise_for_status()
    return r.json()["choices"][0]["message"]["content"].strip()


narration = write_narration("how ocean waves shape a coastline")
print(narration)

Step 3 — Generate the footage

video_id = submit(
    "generateVideo",
    "alibaba/wan-2.5/text-to-video",
    prompt="slow aerial shot of waves breaking against a rocky coastline at golden hour",
    duration=5,
)
video = wait(video_id)
download(video["outputs"][0], "footage.mp4")

Video generation takes minutes, not seconds. In production, register a webhook and let the job call you back rather than holding a polling loop open.

Step 4 — Synthesize the voiceover

The narration from step 2 becomes the input here. Speech, music, and transcription all share the same endpoint — the model decides which one you get.

audio_id = submit(
    "generateAudio",
    "bytedance/seed-audio-1.0",
    text=narration,
    format="mp3",
    sample_rate=44100,
    speech_rate=-5,   # Slightly slower reads better as narration
)
audio = wait(audio_id)
download(audio["outputs"][0], "voiceover.mp3")

See Audio Models for the full parameter set, including voice references.

Step 5 — Combine

ffmpeg -i footage.mp4 -i voiceover.mp3 \
  -c:v copy -c:a aac -shortest narrated.mp4

Optional — Generate subtitles

Feed the voiceover back through a transcription model to get word-level timings for subtitles.

stt_id = submit(
    "generateAudio",
    "bytedance/seed-asr-2.0",
    audio_url=audio["outputs"][0],   # Note the field name: audio_url
    enable_punc=True,
    show_utterances=True,
)
stt = wait(stt_id)

# For transcription models, outputs[0] is the text itself, not a file URL
print(stt["outputs"][0])
for word in stt.get("stt_result", {}).get("words", [])[:10]:
    print(word["start"], word["end"], word["text"])

Transcription models take audio_url, but some other speech-to-text models take audio instead. Check the model's API reference — passing the wrong field name fails validation.

Where to go next

  • Swap the video model for one that accepts a reference image, and drive the look from a still you provide
  • Move polling to webhooks so long jobs do not block your process
  • Run several clips in parallel and concatenate them into a longer sequence
  • Add retry handling from Errors & Rate Limits

Audio Models

Speech, music, and transcription parameters.

SDKs & Client Libraries

A reusable client for these calls.

Predictions

Job status values and polling.

Model Billing

What each step costs.

Last updated on

On this page

SetupStep 1 — Shared helpersStep 2 — Write the script with an LLMStep 3 — Generate the footageStep 4 — Synthesize the voiceoverStep 5 — CombineOptional — Generate subtitlesWhere to go nextRelated