> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Text to Video API

> Generate complete video content from text descriptions using AI.

export const ToolSection = ({type = "image", outputs = [], title = "", productSlug = "", apiSlug = ""}) => <>
    <CardGroup cols={2}>
      <Card title={`${title} API reference`} icon="webhook" horizontal href={`/api-reference/${type}-projects/${apiSlug}`}>
        Request fields, responses, and examples
      </Card>
      <Card title="API quickstart" icon="forward-fast" horizontal href="/get-started/quick-start">
        Install an SDK and complete your first generation
      </Card>
    </CardGroup>

    <p>
      Check <a href="/billing/overview">API pricing</a> and <a href="/api-reference/models">model credit costs</a>, then <a href={`https://magichour.ai/developer?tab=api-keys&ref=docs-tool-${apiSlug}&utm_source=docs&utm_medium=referral&utm_campaign=tools`}>create an API key</a>.
    </p>
    <p>
      To try {title} without code, use the <a href={`https://magichour.ai/products/${productSlug}${productSlug.includes("?") ? "&" : "?"}utm_source=docs&utm_medium=referral&utm_campaign=tools`}>browser tool</a>.
    </p>

    {outputs && outputs.length > 0 && <Tabs>
        {outputs.map((output, idx) => <Tab key={idx} title={`Example Output ${idx + 1}`}>
            <Frame>
              {type === "video" ? <video controls preload="metadata" playsInline className="rounded-lg h-80" src={`${output.src}#t=0.001`} type={`${output.src?.endsWith("mp4") ? 'video/mp4' : "video/webm"}`}>
                </video> : type === "audio" ? <audio controls preload="metadata" className="w-full" src={output.src}>
                  Your browser does not support the audio element.
                </audio> : <img height="320" className="rounded-lg h-80" src={output.src} alt={`${title} example output ${idx + 1}`} />}
            </Frame>
          </Tab>)}
      </Tabs>}

  </>;

## Overview

Text to Video generates complete video content from text descriptions using advanced AI video synthesis. The API creates original video scenes, animations, and visual narratives based on detailed text prompts with customizable styles and durations.

**Processing:** See recent [typical API-job times](/api-reference/processing-times). Jobs run
asynchronously, and duration varies with the input, selected settings, and queue load.

<ToolSection title="Text to Video" productSlug="text-to-video" apiSlug="text-to-video" type="video" />

## How It Works

1. **Write a prompt** - Describe the video you want to create
2. **Set duration** - Choose how long the video should be
3. **API generates the video** - AI creates original video content
4. **Download the result** - Retrieve your generated video

## Use Cases

* **Social media content** - Create engaging videos from ideas
* **Marketing videos** - Generate product and promotional content
* **Concept visualization** - Bring written ideas to visual life
* **Educational content** - Create explainer and demonstration videos
* **Creative projects** - Artistic and experimental video creation

## Best Practices

### Writing Effective Prompts

<Tip>
  **Be specific and descriptive** - Include subject, action, environment, style, and camera motion.
</Tip>

**✅ Good prompts:**

* "A majestic lion walking through golden savanna grass at sunset, cinematic slow motion, warm golden lighting"
* "Underwater scene with colorful tropical fish swimming around a coral reef, crystal clear blue water, nature documentary style"
* "Futuristic city skyline at night with flying cars and neon lights, cyberpunk aesthetic, sweeping aerial shot"

**❌ Avoid:**

* Too vague: "A nice video"
* No action: "A city" (add what's happening)
* Conflicting instructions: "Fast and slow motion"

### Prompt Structure

For best results, include these elements:

| Element     | Description              | Example                                        |
| :---------- | :----------------------- | :--------------------------------------------- |
| Subject     | What/who is in the video | "A golden retriever puppy"                     |
| Action      | What's happening         | "running through a meadow"                     |
| Environment | Where it's happening     | "with wildflowers and mountains in background" |
| Style       | Visual aesthetic         | "cinematic, warm lighting"                     |
| Camera      | How it's filmed          | "slow motion tracking shot"                    |

### Duration Guidelines

| Duration         | Best For                                                                                                                                                     |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3-5 seconds      | Social media clips, GIF-like content                                                                                                                         |
| 5-10 seconds     | Short-form content, product demos                                                                                                                            |
| 10-15 seconds    | Story segments, longer narratives                                                                                                                            |
| Up to 60 seconds | Long-form scenes (model-dependent; see the `end_seconds` values supported by each model in the [API reference](/api-reference/video-projects/text-to-video)) |

## Model selection

`model="default"` currently selects `kling-3.0` on paid tiers and `ltx-2.5` on the free tier. Set a model explicitly when your workflow needs a fixed duration and resolution combination. The examples use `ltx-2.5`, which supports five-second clips at 480p; the paid default does not support 480p.

Other current options include `gemini-omni-1.1`, `minimax-h3`, `seedance-2.0-mini`, `seedance-2.5`, and `veo3.1-lite`. Check the [API reference](/api-reference/video-projects/text-to-video) for each model's supported durations, resolutions, and audio settings. Audio is disabled by default and is unavailable on some models.

## Code Examples

### Basic Text to Video

<CodeGroup>
  ```python Python theme={null}
  from magic_hour import Client
  import os

  client = Client(token=os.getenv("MAGIC_HOUR_API_KEY"))

  result = client.v1.text_to_video.generate(
      end_seconds=5,
      aspect_ratio="16:9",
      style={
          "prompt": "A majestic lion walking through golden savanna grass at sunset, cinematic slow motion"
      },
      name="Nature Video",
      model="ltx-2.5",
      resolution="480p",
      wait_for_completion=True,
      download_outputs=True,
      download_directory="."
  )

  if result.status == "complete":
      print(f"✅ Video complete!")
      print(f"Downloaded to: {result.downloaded_paths}")
      print(f"Credits charged: {result.credits_charged}")
  else:
      print(f"Job ended with status: {result.status}")
      if result.error:
          print(f"Error: {result.error.message}")
  ```

  ```javascript Node.js theme={null}
  import { Client } from "magic-hour";

  const client = new Client({ token: process.env.MAGIC_HOUR_API_KEY });

  const result = await client.v1.textToVideo.generate(
    {
      endSeconds: 5,
      aspectRatio: "16:9",
      style: {
        prompt:
          "A majestic lion walking through golden savanna grass at sunset, cinematic slow motion",
      },
      name: "Nature Video",
      model: "ltx-2.5",
      resolution: "480p",
    },
    {
      waitForCompletion: true,
      downloadOutputs: true,
      downloadDirectory: ".",
    }
  );

  if (result.status === "complete") {
    console.log(`✅ Video complete!`);
    console.log(`Downloaded to: ${result.downloadedPaths}`);
  } else {
    console.error(`Job ended with status: ${result.status}`);
    if (result.error) console.error(result.error.message);
  }
  ```
</CodeGroup>

## Pricing

Text to Video pricing depends on the model, resolution, and duration you choose. You pay for the frames that render. The create response estimates `credits_charged`; read the completed job for the final cost.

## Resolution Limits

Supported resolutions are 360p, 480p, 720p, 1080p, and 4k, depending on the model and your subscription tier. For example, `kling-3.0` supports 4k. Output defaults to `720p` on paid tiers and `480p` on the free tier. See [Resolution Limits](/billing/resolution-limits) for tier details.

<Tip>
  **Try this in our Google Colab Cookbook:** [Run this API with sample
  code](https://colab.research.google.com/drive/1NTHL_lr_s-qBJ-mSecSXPzRLi9_V5JiU?usp=sharing). Just
  add your API key.
</Tip>

## API Reference

<Card title="Text to Video API Reference" icon="webhook" href="/api-reference/video-projects/text-to-video">
  View full API specification
</Card>

## Related Tools

<CardGroup cols={2}>
  <Card title="Image to Video" icon="image" href="/tools/video/image-to-video">
    Animate static images into videos
  </Card>

  <Card title="Animation" icon="film" href="/tools/video/animation">
    Create animated videos with motion effects
  </Card>
</CardGroup>