Together Video Generation

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

Installation

# Python (recommended)
uv init  # optional, if starting a new project
uv add together

# or with pip
pip install together

# TypeScript / JavaScript
npm install together-ai

Set your API key:

export TOGETHER_API_KEY=<your-api-key>

Quick Start

Text-to-Video

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
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)

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));
}

# 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
  }'

# 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"

Image-to-Video (Keyframes)

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}],
)

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));
}

# 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}]
  }'

# 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"

Reference Images

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

Parameters

Job Status Flow

Guidance Scale Tips

• 6-7: Creative, more interpretation
• 7-9: Balanced (recommended)
• 9-10: Strict prompt adherence
• >12: Avoid — causes artifacts

Key Models

See references/models.md for the complete model table.

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