---
title: "Media · Video · Generate a video from a text prompt"
method: POST
path: "/api/v1/tools/text-to-video"
tags: ["generate"]
---

# Media · Video · Generate a video from a text prompt

`POST /api/v1/tools/text-to-video`

## Request

- Base URL: `https://api.simplified.com`
- URL: `https://api.simplified.com/api/v1/tools/text-to-video`
- Auth: API key in header `Authorization`

Required JSON: `payload.title` (the short text prompt). `description` can
add context. `voice_id` is optional; use `listVoices` to choose a specific
voice for the requested locale. Captions default to on, stock videos are
the default visual source, and `should_export` defaults to true. To
customize captions, use `caption_style` for inline settings or
`brand_kit_config.caption_style_id` for a saved brand style.

Generation costs credits and returns a `task_id`. Poll `getTaskResult`
until SUCCESS or FAILURE. On SUCCESS, read `info.export_id` (also present
in `detail.export_id`). When `should_export=true`, poll `getVideoExport`
separately until its `status` is 3, then read `assets.urls[0]`. Task
SUCCESS means the export was queued; the MP4 may take longer to render.

## Request body

- object
  - `payload` ApiV1ToolsTextToVideoPostRequestBodyContentApplicationJsonSchemaPayload, required
    - `title` string, required: Text prompt describing the video to generate.
    - `description` string: Additional detail or context for the generation.
    - `keywords` string: Comma-separated keywords to guide visuals.
    - `tone` 'professional' | 'informal' | 'optimistic' | 'pessimistic' | 'joyful' | 'sad' | 'sincere' | 'hypocritical' | 'fearful' | 'hopeful' | 'happy' | 'serious'
    - `creativity_level` number, double: Script generation creativity; defaults to 0.5.
    - `language_code` string: Exact BCP-47 locale for voiceover and captions, for example en-US.
    - `voice_id` string, uuid: Optional narrator UUID from listVoices for the requested language_code.
    - `aspect_ratio` '9:16' | '1:1' | '16:9': Video aspect ratio. Exported output is MP4.
    - `no_runs` integer: Requests up to five script candidates internally; this endpoint returns one video.
    - `logo_id` string, uuid: Legacy alias for brand_kit_config.logo_id; canonical configuration takes precedence.
    - `caption_style_id` string, uuid: Legacy brand caption-style UUID alias for brand_kit_config.caption_style_id. For inline styling use caption_style.
    - `media_source_config` MediaSourceConfig: Choose stock footage, stock images, AI images, AI video clips, or uploaded assets. AI-generated visuals consume additional credits.
      - `type` 'stock_videos' | 'stock_images' | 'ai_images' | 'ai_videos' | 'custom', required
      - `mode` 'speed' | 'quality': For ai_videos: speed or quality mode.
    - `brand_kit_config` BrandKitConfig
      - `logo_id` string, uuid, nullable
      - `caption_style_id` string, uuid, nullable
    - `enable_captions` boolean
    - `caption_style` CaptionStyle: Optional inline caption styling. Choose an editor animation with type or numeric id (or both). Supported pairs are caption1–caption5/1–5 and caption8–caption14/8–14; IDs 6 and 7 are not offered. The API fills extras.id for the renderer and rejects unsupported or mismatched pairs. Styles are Subtitle (1), Highlight (2), Karaoke (3), Impact (4), Reveal (5), Slab (8), Block (9), Focus (10), Hormozi (11), Social (12), Retro (13), and Breeze (14). For a saved brand caption style, use the UUID in brand_kit_config.caption_style_id instead. Inline styling takes precedence when both are supplied.
      - `type` 'caption1' | 'caption2' | 'caption3' | 'caption4' | 'caption5' | 'caption8' | 'caption9' | 'caption10' | 'caption11' | 'caption12' | 'caption13' | 'caption14': Animation type. Omit with id to infer it; caption11 is the default when no inline style is set.
      - `id` '1' | '2' | '3' | '4' | '5' | '8' | '9' | '10' | '11' | '12' | '13' | '14': Numeric animation ID matching type. The API copies it to extras.id.
      - `extras` CaptionStyleExtras: Optional renderer settings for colors, shadow, textCase (0 original, 1 lowercase, 2 uppercase, 3 title case), lineHeight, float, and rotate. extras.id is filled from type/id; a conflicting value is rejected. Unsupported keys may have no effect.
        - `id` integer: Animation ID; inferred from type or top-level id when omitted.
        - `textColor` string: CSS color for caption text, for example rgba(255,255,255,1).
        - `textBackgroundColor` string: CSS background color behind caption text.
        - `strokeColor` string: CSS color for the text outline.
        - `highlightColor1` string
        - `highlightColor2` string
        - `lineHeight` number, double
        - `textCase` '0' | '1' | '2' | '3'
        - `float` boolean
        - `rotate` boolean
        - `shadow` object: Shadow settings such as color, blur, offsetX, and offsetY.
      - `fontFamily` string, nullable: Font family for generated captions, for example Rubik.
      - `fontWeight` integer, nullable: Numeric font weight, for example 700.
    - `assets` CustomVideoMedia[]: Required when media_source_config.type=custom. Visuals are selected from these media URLs.
      - `mime` 'image' | 'video', required
      - `source_url` string, uri, required: Public URL of uploaded image/video to use as a visual.
      - `start_time` number, double: Optional start offset in milliseconds for video visuals.
  - `should_export` boolean: Whether to export the final video file.

## Response `202`

Async task queued.

- AsyncTaskResponse
  - `task_id` string, required: Poll GET /api/v1/tasks/{task_id} until SUCCESS or FAILURE.

---

[API](https://skmtc.dev/simplified/apis/video-tools.md) - [All operations](https://skmtc.dev/simplified/apis/video-tools/llms.txt) - [OpenAPI document](https://skmtc.dev/simplified/apis/video-tools/revisions/e96eaa27d93b?raw)