Back to Details

together-video

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Together Video Generation

Together 视频生成

Overview

概述

Generate videos asynchronously — submit a job, poll for completion, download the result.
  • Endpoint: 
    /v2/videos
  • Async workflow: create job → poll status → download video
  • 15+ models from Google, OpenAI, MiniMax, Kuaishou, ByteDance, PixVerse, Vidu
异步生成视频——提交任务、轮询完成状态、下载结果。
  • 接口地址：
    /v2/videos
  • 异步工作流：创建任务 → 轮询状态 → 下载视频
  • 包含来自Google、OpenAI、MiniMax、快手、字节跳动、PixVerse、Vidu的15+款模型

Quick Start

快速开始

Text-to-Video

文生视频

python
import time
from together import Together
client = Together()

job = client.videos.create(
    prompt="A serene sunset over the ocean with gentle waves",
    model="minimax/video-01-director",
    width=1366,
    height=768,
)
print(f"Job ID: {job.id}")
python
import time
from together import Together
client = Together()

job = client.videos.create(
    prompt="A serene sunset over the ocean with gentle waves",
    model="minimax/video-01-director",
    width=1366,
    height=768,
)
print(f"Job ID: {job.id}")

Poll until completion

Poll until completion

while True: status = client.videos.retrieve(job.id) if status.status == "completed": print(f"Video URL: {status.outputs.video_url}") break elif status.status == "failed": print("Failed") break time.sleep(5)

```typescript
import Together from "together-ai";
const together = new Together();

const job = await together.videos.create({
  prompt: "A serene sunset over the ocean with gentle waves",
  model: "minimax/video-01-director",
  width: 1366, height: 768,
});

// Poll until completion
while (true) {
  const status = await together.videos.retrieve(job.id);
  if (status.status === "completed") {
    console.log(`Video URL: ${status.outputs.video_url}`);
    break;
  } else if (status.status === "failed") break;
  await new Promise(r => setTimeout(r, 5000));
}
shell
undefined
while True: status = client.videos.retrieve(job.id) if status.status == "completed": print(f"Video URL: {status.outputs.video_url}") break elif status.status == "failed": print("Failed") break time.sleep(5)

```typescript
import Together from "together-ai";
const together = new Together();

const job = await together.videos.create({
  prompt: "A serene sunset over the ocean with gentle waves",
  model: "minimax/video-01-director",
  width: 1366, height: 768,
});

// Poll until completion
while (true) {
  const status = await together.videos.retrieve(job.id);
  if (status.status === "completed") {
    console.log(`Video URL: ${status.outputs.video_url}`);
    break;
  } else if (status.status === "failed") break;
  await new Promise(r => setTimeout(r, 5000));
}
shell
undefined

Create a video generation job

Create a video generation job

curl -X POST "https://api.together.xyz/v2/videos"
-H "Authorization: Bearer $TOGETHER_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "minimax/video-01-director", "prompt": "A serene sunset over the ocean with gentle waves", "width": 1366, "height": 768 }'
curl -X POST "https://api.together.xyz/v2/videos"
-H "Authorization: Bearer $TOGETHER_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "minimax/video-01-director", "prompt": "A serene sunset over the ocean with gentle waves", "width": 1366, "height": 768 }'

Poll for completion (replace $JOB_ID with the id from the create response)

Poll for completion (replace $JOB_ID with the id from the create response)

curl -X GET "https://api.together.xyz/v2/videos/$JOB_ID"
-H "Authorization: Bearer $TOGETHER_API_KEY"
undefined
curl -X GET "https://api.together.xyz/v2/videos/$JOB_ID"
-H "Authorization: Bearer $TOGETHER_API_KEY"
undefined

Image-to-Video (Keyframes)

图生视频（关键帧）

python
import base64, requests

image_url = "https://example.com/photo.jpg"
img_data = base64.b64encode(requests.get(image_url).content).decode("utf-8")

job = client.videos.create(
    prompt="Smooth camera zoom out",
    model="minimax/hailuo-02",
    frame_images=[{"input_image": img_data, "frame": 0}],
)
typescript
import * as fs from "fs";
import Together from "together-ai";
const together = new Together();

// Load and encode your image
const imageBuffer = fs.readFileSync("keyframe.jpg");
const base64Image = imageBuffer.toString("base64");

const job = await together.videos.create({
  prompt: "Smooth camera zoom out",
  model: "minimax/hailuo-02",
  frame_images: [{ input_image: base64Image, frame: 0 }],
});

// Poll until completion
while (true) {
  const status = await together.videos.retrieve(job.id);
  if (status.status === "completed") {
    console.log(`Video URL: ${status.outputs.video_url}`);
    break;
  } else if (status.status === "failed") break;
  await new Promise(r => setTimeout(r, 5000));
}
shell
undefined
python
import base64, requests

image_url = "https://example.com/photo.jpg"
img_data = base64.b64encode(requests.get(image_url).content).decode("utf-8")

job = client.videos.create(
    prompt="Smooth camera zoom out",
    model="minimax/hailuo-02",
    frame_images=[{"input_image": img_data, "frame": 0}],
)
typescript
import * as fs from "fs";
import Together from "together-ai";
const together = new Together();

// Load and encode your image
const imageBuffer = fs.readFileSync("keyframe.jpg");
const base64Image = imageBuffer.toString("base64");

const job = await together.videos.create({
  prompt: "Smooth camera zoom out",
  model: "minimax/hailuo-02",
  frame_images: [{ input_image: base64Image, frame: 0 }],
});

// Poll until completion
while (true) {
  const status = await together.videos.retrieve(job.id);
  if (status.status === "completed") {
    console.log(`Video URL: ${status.outputs.video_url}`);
    break;
  } else if (status.status === "failed") break;
  await new Promise(r => setTimeout(r, 5000));
}
shell
undefined

Create an image-to-video job (replace $BASE64_IMAGE with your base64-encoded image)

Create an image-to-video job (replace $BASE64_IMAGE with your base64-encoded image)

curl -X POST "https://api.together.xyz/v2/videos"
-H "Authorization: Bearer $TOGETHER_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "minimax/hailuo-02", "prompt": "Smooth camera zoom out", "frame_images": [{"input_image": "$BASE64_IMAGE", "frame": 0}] }'
curl -X POST "https://api.together.xyz/v2/videos"
-H "Authorization: Bearer $TOGETHER_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "minimax/hailuo-02", "prompt": "Smooth camera zoom out", "frame_images": [{"input_image": "$BASE64_IMAGE", "frame": 0}] }'

Poll for completion (replace $JOB_ID with the id from the create response)

Poll for completion (replace $JOB_ID with the id from the create response)

curl -X GET "https://api.together.xyz/v2/videos/$JOB_ID"
-H "Authorization: Bearer $TOGETHER_API_KEY"
undefined
curl -X GET "https://api.together.xyz/v2/videos/$JOB_ID"
-H "Authorization: Bearer $TOGETHER_API_KEY"
undefined

Reference Images

参考图

python
job = client.videos.create(
    prompt="A cat dancing energetically",
    model="minimax/hailuo-02",
    reference_images=["https://example.com/cat.jpg"],
)
python
job = client.videos.create(
    prompt="A cat dancing energetically",
    model="minimax/hailuo-02",
    reference_images=["https://example.com/cat.jpg"],
)

Parameters

参数

ParameterTypeDescriptionDefault
prompt
stringText description (required for all models except Kling)-
model
stringModel ID (required)-
width
intVideo width1366
height
intVideo height768
seconds
intDuration (1-10)5-6
fps
intFrames per second24-25
steps
intDiffusion stepsvaries
guidance_scale
floatPrompt adherence (6-10)varies
seed
intRandom seedrandom
negative_prompt
stringWhat to exclude-
frame_images
arrayKeyframe images (base64)-
reference_images
arrayStyle reference URLs-
output_format
string"MP4" or "WEBM""MP4"
output_quality
intBitrate/quality (lower = higher quality)20
参数类型描述默认值
prompt
string文本描述（除Kling外所有模型必填）-
model
string模型ID（必填）-
width
int视频宽度1366
height
int视频高度768
seconds
int视频时长（1-10）5-6
fps
int帧率24-25
steps
int扩散步数依模型而定
guidance_scale
float提示词贴合度（6-10）依模型而定
seed
int随机种子随机生成
negative_prompt
string需要排除的内容描述-
frame_images
array关键帧图片（base64格式）-
reference_images
array风格参考图URL-
output_format
string"MP4" 或 "WEBM""MP4"
output_quality
int码率/质量（数值越低质量越高）20

Job Status Flow

任务状态流转

StatusDescription
queued
Waiting in queue
in_progress
Generating
completed
Done — video URL available
failed
Check 
info.errors
cancelled
Job cancelled
状态描述
queued
队列等待中
in_progress
生成中
completed
已完成——可获取视频URL
failed
生成失败——查看
info.errors
获取详情
cancelled
任务已取消

Guidance Scale Tips

引导系数使用提示

  • 6-7: Creative, more interpretation
  • 7-9: Balanced (recommended)
  • 9-10: Strict prompt adherence
  • >12: Avoid — causes artifacts
  • 6-7: 创意性强，模型发挥空间更大
  • 7-9: 效果均衡（推荐）
  • 9-10: 严格遵循提示词描述
  • >12: 不建议使用——会产生伪影

Key Models

核心模型

ModelAPI StringDurationDimensions
Veo 3.0
google/veo-3.0
8s1280x720, 1920x1080
Veo 3.0 + Audio
google/veo-3.0-audio
8s1280x720, 1920x1080
Sora 2
openai/sora-2
8s1280x720
Hailuo 02
minimax/hailuo-02
10s1366x768, 1920x1080
Kling 2.1 Master
kwaivgI/kling-2.1-master
5s1920x1080
Seedance 1.0 Pro
ByteDance/Seedance-1.0-pro
5sMultiple
PixVerse v5
pixverse/pixverse-v5
5sMultiple
Vidu 2.0
vidu/vidu-2.0
8sMultiple
See references/models.md for the complete model table.
模型API标识时长分辨率
Veo 3.0
google/veo-3.0
8s1280x720, 1920x1080
Veo 3.0 + Audio
google/veo-3.0-audio
8s1280x720, 1920x1080
Sora 2
openai/sora-2
8s1280x720
Hailuo 02
minimax/hailuo-02
10s1366x768, 1920x1080
Kling 2.1 Master
kwaivgI/kling-2.1-master
5s1920x1080
Seedance 1.0 Pro
ByteDance/Seedance-1.0-pro
5s多种
PixVerse v5
pixverse/pixverse-v5
5s多种
Vidu 2.0
vidu/vidu-2.0
8s多种
查看 references/models.md 获取完整模型列表。

Resources

相关资源

  • Full model details: See references/models.md
  • Runnable script: See scripts/generate_video.py — async video generation with polling helper (v2 SDK)
  • Runnable script (TypeScript): See scripts/generate_video.ts — minimal OpenAPI 
    x-codeSamples
    extraction for create/retrieve video (TypeScript SDK)
  • Official docs: Videos Overview
  • API reference: Create Video API
  • 完整模型详情: 查看 references/models.md
  • 可运行脚本: 查看 scripts/generate_video.py —— 带轮询辅助功能的异步视频生成示例（v2 SDK）
  • 可运行脚本（TypeScript）: 查看 scripts/generate_video.ts —— 视频创建/查询接口的最小OpenAPI 
    x-codeSamples
    示例（TypeScript SDK）
  • 官方文档: 视频功能概述
  • API参考: 视频创建API