---
title: "Create video"
method: POST
path: "/v2/videos"
tags: ["Video"]
---

# Create video

`POST /v2/videos`

## Request

- Base URL: `https://api.together.ai`
- URL: `https://api.together.ai/v2/videos`
- Auth: HTTP bearer

Create a video

## Request body

- CreateVideoBody: Parameters for creating a new video generation job.
  - `model` string, required: The model to be used for the video creation request.
  - `prompt` string: Text prompt that describes the video to generate.
  - `height` integer
  - `width` integer
  - `resolution` string: Video resolution.
  - `ratio` string: Aspect ratio of the video.
  - `seconds` string: Clip duration in seconds.
  - `fps` integer: Frames per second. Defaults to 24.
  - `steps` integer: The number of denoising steps the model performs during video generation. More steps typically result in higher quality output but require longer processing time.
  - `seed` integer: Seed to use in initializing the video generation. Using the same seed allows deterministic video generation. If not provided a random seed is generated for each request.
  - `guidance_scale` integer: Controls how closely the video generation follows your prompt. Higher values make the model adhere more strictly to your text description, while lower values allow more creative freedom. guidence_scale affects both visual content and temporal consistency.Recommended range is 6.0-10.0 for most video models. Values above 12 may cause over-guidance artifacts or unnatural motion patterns.
  - `output_format` 'MP4' | 'WEBM'
  - `output_quality` integer: Compression quality. Defaults to 20.
  - `negative_prompt` string: Similar to prompt, but specifies what to avoid instead of what to include
  - `generate_audio` boolean: Whether to generate audio for the video.
  - `media` VideoMedia: Contains all media inputs for video generation. Accepted fields depend on the model type.
    - `frame_images` VideoFrameImageInput[]: Array of images to guide video generation at specific timeline positions.
      - `input_image` string, required: URL path to hosted image that is used for a frame
      - `frame` union: Optional param to specify where to insert the frame. If this is omitted, the following heuristics are applied: - frame_images size is one, frame is first. - If size is two, frames are first and last. - If size is larger, frames are first, last and evenly spaced between.
        - number
        - 'first' | 'last'
    - `frame_videos` VideoRef[]: Array of video clips to use as starting clips.
      - `video` string, required: URL of the video.
    - `reference_images` string[]: Array of image URLs that guide the general appearance across the video.
    - `reference_videos` VideoRef[]: Array of reference videos.
      - `video` string, required: URL of the video.
    - `source_video` union: Source video to edit. Accepts a URL string or an object with a "video" key.
      - string
      - VideoRef
        - `video` string, required: URL of the video.
    - `audio_inputs` union[]: Array of audio inputs. Each element accepts a URL string or an object with an "audio" key.
      - union
        - string
        - AudioRef
          - `audio` string, required: URL of the audio.

## Response `200`

Success

- VideoJob: Structured information describing a generated video job.
  - `id` string, required: Unique identifier for the video job.
  - `object` 'video': The object type, which is always video.
  - `model` string, required: The video generation model that produced the job.
  - `status` 'in_progress' | 'completed' | 'failed', required: Current lifecycle status of the video job.
  - `created_at` number, required: Unix timestamp (seconds) for when the job was created.
  - `completed_at` number: Unix timestamp (seconds) for when the job completed, if finished.
  - `size` string, required: The resolution of the generated video.
  - `seconds` string, required: Duration of the generated clip in seconds.
  - `error` object: Error payload that explains why generation failed, if applicable.
    - `code` string
    - `message` string, required
  - `outputs` object: Available upon completion, the outputs provides the cost charged and the hosted url to access the video
    - `cost` integer, required: The cost of generated video charged to the owners account.
    - `video_url` string, required: URL hosting the generated video

## Changes

- **2026-10-22** `bb5257b3173a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/together/apis/together-apis/changes/v2/videos/post.md)

---

[API](https://skmtc.dev/together/apis/together-apis.md) - [All operations](https://skmtc.dev/together/apis/together-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/together/apis/together-apis/revisions/93438ddac711?raw)