Video generation

The video API turns a text prompt (or an image) into a short video. Generation takes from several seconds to a few minutes, so the API is asynchronous: you create a job, poll it until it finishes, then read the result URL.

Endpoint	What it does
`POST /v1/videos`	Create a video job from a prompt
`GET /v1/videos/{id}`	Poll a job for its status and result
`GET /v1/videos/{id}/content`	Redirect to the finished video file
`DELETE /v1/videos/{id}`	Cancel or delete a job

New here? The three steps below take you from a prompt to a saved .mp4.

Step 1: Create a job

A request needs a model and a prompt. Browse the ids on the video models page.

curl

curl https://api.deepshi.ai/v1/videos \
  -H "Authorization: Bearer $DEEPSHI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "a paper boat drifting down a rain-soaked street",
    "resolution": "480p",
    "duration": 4
  }'

You get back a job object with status: "queued". Save the id so you can poll it in Step 2.

{
  "id": "vid_a1b2c3...",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "queued",
  "size": "480p",
  "seconds": "4"
}

Field	What it is
`id`	The job id. Pass it to the poll, content, and delete endpoints.
`status`	Lifecycle state: `queued`, `in_progress`, `completed`, or `failed`.
`size`	The resolution the job will bill at.
`seconds`	The clip length the job will bill at, in seconds.

Step 2: Poll for completion

Call GET /v1/videos/{id} on an interval (every few seconds is plenty) until status is completed or failed. A completed job carries the result under videos[].

{
  "id": "vid_a1b2c3...",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "size": "480p",
  "seconds": "4",
  "created_at": 1783112379,
  "videos": [
    { "type": "url", "url": "https://media.cdn-deepshi.com/videos/....mp4", "content_type": "video/mp4" }
  ]
}

Field	What it is
`videos[].url`	A direct link to the finished `.mp4`.
`videos[].content_type`	The media type, always `video/mp4`.
`status: "failed"`	Generation failed. An `error` object explains why, and you are not charged.

Step 3: Get the file

Use videos[].url directly, or call GET /v1/videos/{id}/content to be redirected to the same file. The full loop looks like this:

import time, requests

BASE = "https://api.deepshi.ai/v1"
headers = {"Authorization": "Bearer YOUR_DEEPSHI_API_KEY"}

# 1. create
job = requests.post(f"{BASE}/videos", headers=headers, json={
    "model": "grok-imagine-video",
    "prompt": "a paper boat drifting down a rain-soaked street",
    "resolution": "480p",
    "duration": 4,
}).json()

# 2. poll
while job["status"] not in ("completed", "failed"):
    time.sleep(5)
    job = requests.get(f"{BASE}/videos/{job['id']}", headers=headers).json()

if job["status"] == "failed":
    raise SystemExit(job.get("error"))

# 3. download
url = job["videos"][0]["url"]
open("output.mp4", "wb").write(requests.get(url).content)
print("saved output.mp4")

const BASE = "https://api.deepshi.ai/v1";
const headers = {
  Authorization: "Bearer YOUR_DEEPSHI_API_KEY",
  "Content-Type": "application/json",
};

// 1. create
let job = await (await fetch(`${BASE}/videos`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "grok-imagine-video",
    prompt: "a paper boat drifting down a rain-soaked street",
    resolution: "480p",
    duration: 4,
  }),
})).json();

// 2. poll
while (!["completed", "failed"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (await fetch(`${BASE}/videos/${job.id}`, { headers })).json();
}
if (job.status === "failed") throw new Error(JSON.stringify(job.error));

// 3. download
const url = job.videos[0].url;
const buf = Buffer.from(await (await fetch(url)).arrayBuffer());
require("node:fs").writeFileSync("output.mp4", buf);
console.log("saved output.mp4");

# 1. create -> capture the id
ID=$(curl -s https://api.deepshi.ai/v1/videos \
  -H "Authorization: Bearer $DEEPSHI_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"grok-imagine-video","prompt":"a paper boat drifting down a rain-soaked street","resolution":"480p","duration":4}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")

# 2. poll until it is done
while true; do
  STATUS=$(curl -s https://api.deepshi.ai/v1/videos/$ID \
    -H "Authorization: Bearer $DEEPSHI_API_KEY" \
    | python3 -c "import sys,json;print(json.load(sys.stdin)['status'])")
  echo "status: $STATUS"; [ "$STATUS" = completed ] || [ "$STATUS" = failed ] && break
  sleep 5
done

# 3. follow the content redirect to the file
curl -sL https://api.deepshi.ai/v1/videos/$ID/content \
  -H "Authorization: Bearer $DEEPSHI_API_KEY" -o output.mp4

A video id is scoped to the key that created it. Another key cannot poll, download, or delete it. Download anything you want to keep as soon as the job completes.

Image to video

To animate a still image, add input_reference with a public image URL or a data: URI. The model runs in image-to-video mode. Only models whose model card lists image-to-video support accept it.

{
  "model": "wan-2.5",
  "prompt": "the boat sails forward as the camera pulls back",
  "input_reference": "https://example.com/boat.png",
  "resolution": "480p",
  "duration": 5
}

Choosing a model

Each video model supports different resolutions, durations, aspect ratios, and audio options. There are two ways to see them:

The video models page, with a card per model showing its resolution tiers, prompt limit, and whether it supports image-to-video and audio.
GET /v1/models, the same facts as JSON, scoped to your key.

curl https://api.deepshi.ai/v1/models \
  -H "Authorization: Bearer $DEEPSHI_API_KEY"

Each video entry lists the parameters it accepts (with type, allowed values, and default), plus prompt_max_length and its modalities:

Example video model entry

{
  "id": "veo3.1",
  "object": "model",
  "output_modalities": ["video"],
  "input_modalities": ["text", "image"],
  "prompt_max_length": 20000,
  "parameters": {
    "resolution":     { "type": "enum",    "values": ["720p", "1080p", "4k"], "default": "720p" },
    "duration":       { "type": "enum",    "values": [4, 6, 8], "default": 8, "unit": "seconds" },
    "aspect_ratio":   { "type": "enum",    "values": ["16:9", "9:16"], "default": "16:9" },
    "generate_audio": { "type": "boolean", "default": true }
  }
}

Common parameters

These apply across video models. A model ignores any field it does not support, so don’t carry one model’s parameters over to another.

string

required

The video model id. Take it from GET /v1/models.

string

required

What to generate. Each model caps the length; over its prompt_max_length returns 400.

string

A public image URL or data: URI. Switches the model to image-to-video. Only models whose card lists image-to-video support accept it.

string

Resolution tier, such as 480p, 720p, 1080p, or 4k. Allowed values are per model. Sets the billed price on resolution-priced models.

integer

Clip length in seconds. An enum for some models (for example 4, 6, 8), a range for others. The billed length.

string

Aspect ratio such as 16:9 or 9:16. Some models add auto in image-to-video mode.

boolean

Generate a soundtrack, on models that support audio.

string

What to avoid in the output, on models that support it.

integer

Seed for reproducible output, on models that support it. Omit for a random seed.

Pricing

Video is priced per second of output. The final cost is the model’s per-second rate times the clip duration. The rate can depend on the resolution and whether audio is on. Per-model rates are on deepshi.ai. You are billed only for delivered output. A job is charged once, when it completes. A job that fails, or that you cancel before it finishes, is not charged. Unlike image responses, video job objects do not carry an inline usage.cost. Check per-model rates and your balance on deepshi.ai.

Canceling a job

DELETE /v1/videos/{id} cancels a job that is still running and stops it from billing, or removes a job you no longer need. It returns a confirmation:

{ "id": "vid_a1b2c3...", "deleted": true, "object": "video.deleted" }

Canceling before the video is delivered means you are not charged. A job that already completed has already billed, so canceling it does not refund it.

Chat

Media

Cookbook

Integrations

Step 1: Create a job

Step 2: Poll for completion

Step 3: Get the file

Image to video

Choosing a model

Common parameters

Pricing

Canceling a job

Next steps

Video models

Credits & billing

​Step 1: Create a job

​Step 2: Poll for completion

​Step 3: Get the file

​Image to video

​Choosing a model

​Common parameters

​Pricing

​Canceling a job

​Next steps

Video models

Credits & billing

Step 1: Create a job

Step 2: Poll for completion

Step 3: Get the file

Image to video

Choosing a model

Common parameters

Pricing

Canceling a job

Next steps