AI Video/Generate AI video

Generate AI video

POST/api/v1/ai_video

Generate a video with a frontier AI model. Provide first_frame (optionally end_frame) for image-to-video, refs for multimodal text-to-video, or neither for pure text-to-video. Credits are charged on submission and refunded automatically if generation fails; poll GET /api/v1/ai_video for progress.

Beta: available to allowlisted API keys. Per-key concurrency is limited during beta; submissions beyond the limit are rejected rather than queued.

Headers

X-API-KeystringRequired

Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Request body

model_idstringRequired

Model to generate with. Use an id from GET /api/v1/ai_video/models, e.g. seedance-2.0.

promptstringRequired

Text description of the video to generate. For image-to-video it describes the motion applied to first_frame.

client_request_idstring | nullOptional

Optional idempotency key. Resubmitting with the same value within 24h returns the original task instead of creating (and charging) a new one. Safe for retries.

duration_secinteger | nullOptional

Clip length in seconds. Allowed values vary by model (see GET /api/v1/ai_video/models); defaults to the model default. Longer clips cost more credits.

aspect_ratiostring | nullOptional

Aspect ratio such as 16:9 / 9:16 / 1:1. Allowed values vary by model; defaults to the model default.

resolutionstring | nullOptional

Output resolution such as 720p / 1080p. Allowed values vary by model; defaults to the model default. Higher resolutions cost more credits.

generate_audioboolean | nullOptional

Whether to generate a native audio track. Defaults to the model default (usually true).

first_frameMediaRef | nullOptional

Image to use as the first frame; providing it switches the request to image-to-video. Mutually exclusive with refs.

Show 3 propertiesHide 3 properties

asset_idstring | nullOptional

Asset ID from POST /api/v1/asset; use for materials reused across requests.

urlstring | nullOptional

Publicly accessible media URL for one-off use; not added to your asset library.

inline_dataInlineDataModel | nullOptional

Inline base64 media data for one-off use; not added to your asset library.

Show 2 propertiesHide 2 properties

mime_typestringRequired

MIME type of the inline data, used to detect image vs audio. Audio: ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav']; images: ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

datastringRequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

end_frameMediaRef | nullOptional

Image to use as the last frame. Requires first_frame.

Show 3 propertiesHide 3 properties

asset_idstring | nullOptional

Asset ID from POST /api/v1/asset; use for materials reused across requests.

urlstring | nullOptional

Publicly accessible media URL for one-off use; not added to your asset library.

inline_dataInlineDataModel | nullOptional

Inline base64 media data for one-off use; not added to your asset library.

Show 2 propertiesHide 2 properties

mime_typestringRequired

datastringRequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

refsarray of MediaRef | nullOptional

Multimodal reference materials (image/video/audio) that guide text-to-video. Mutually exclusive with first_frame.

Show 3 propertiesHide 3 properties

asset_idstring | nullOptional

Asset ID from POST /api/v1/asset; use for materials reused across requests.

urlstring | nullOptional

Publicly accessible media URL for one-off use; not added to your asset library.

inline_dataInlineDataModel | nullOptional

Inline base64 media data for one-off use; not added to your asset library.

Show 2 propertiesHide 2 properties

mime_typestringRequired

datastringRequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)

video_idstringRequired

Identifier of the created task. Poll GET /api/v1/ai_video with it to track progress.

statusstringOptionalDefault "queued"

Initial task status; always queued right after creation.

cost_creditintegerOptionalDefault 0

Credits charged for this task on submission; auto-refunded if generation fails.

Errors

All error responses share one JSON envelope: an error object with a numeric code, a human-readable message, an optional details string, and an optional hint giving an actionable next step (handy for AI agents).

errorErrorDetailRequired

Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.

Show 4 propertiesHide 4 properties

codeintegerRequired

Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.

messagestringRequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.

detailsstring | nullOptional

Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.

hintstring | nullOptional

Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.

Request

curl -X POST 'https://openapi.visionstory.ai/api/v1/ai_video' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": true,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "refs": [
    {
      "asset_id": null,
      "url": null,
      "inline_data": null
    }
  ]
}'

import requests

url = "https://openapi.visionstory.ai/api/v1/ai_video"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
}
payload = {
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": True,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": None
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": None
  },
  "refs": [
    {
      "asset_id": None,
      "url": None,
      "inline_data": None
    }
  ]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/ai_video", {
  method: "POST",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "client_request_id": "client_request_a1b2c3d4e5f6",
    "model_id": "seedance-2.0",
    "prompt": "string",
    "duration_sec": 10,
    "aspect_ratio": "string",
    "resolution": "string",
    "generate_audio": true,
    "first_frame": {
      "asset_id": "7241058823145623552",
      "url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null
    },
    "end_frame": {
      "asset_id": "7241058823145623552",
      "url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null
    },
    "refs": [
      {
        "asset_id": null,
        "url": null,
        "inline_data": null
      }
    ]
  }),
});
const data = await response.json();
console.log(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": true,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "refs": [
    {
      "asset_id": null,
      "url": null,
      "inline_data": null
    }
  ]
}`)
	req, _ := http.NewRequest("POST", "https://openapi.visionstory.ai/api/v1/ai_video", bytes.NewBuffer(payload))
	req.Header.Set("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://openapi.visionstory.ai/api/v1/ai_video"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "client_request_id": "client_request_a1b2c3d4e5f6",
          "model_id": "seedance-2.0",
          "prompt": "string",
          "duration_sec": 10,
          "aspect_ratio": "string",
          "resolution": "string",
          "generate_audio": true,
          "first_frame": {
            "asset_id": "7241058823145623552",
            "url": "https://cdn.visionstory.ai/example.png",
            "inline_data": null
          },
          "end_frame": {
            "asset_id": "7241058823145623552",
            "url": "https://cdn.visionstory.ai/example.png",
            "inline_data": null
          },
          "refs": [
            {
              "asset_id": null,
              "url": null,
              "inline_data": null
            }
          ]
        }"""))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

<?php
$ch = curl_init("https://openapi.visionstory.ai/api/v1/ai_video");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type: application/json",
]);
$payload = <<<'JSON'
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": true,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "refs": [
    {
      "asset_id": null,
      "url": null,
      "inline_data": null
    }
  ]
}
JSON;
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

require "net/http"
require "uri"

uri = URI("https://openapi.visionstory.ai/api/v1/ai_video")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "sk-vs-xxxxxxxxxxxxxxxxxxx"
request["Content-Type"] = "application/json"
request.body = <<~JSON
  {
    "client_request_id": "client_request_a1b2c3d4e5f6",
    "model_id": "seedance-2.0",
    "prompt": "string",
    "duration_sec": 10,
    "aspect_ratio": "string",
    "resolution": "string",
    "generate_audio": true,
    "first_frame": {
      "asset_id": "7241058823145623552",
      "url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null
    },
    "end_frame": {
      "asset_id": "7241058823145623552",
      "url": "https://cdn.visionstory.ai/example.png",
      "inline_data": null
    },
    "refs": [
      {
        "asset_id": null,
        "url": null,
        "inline_data": null
      }
    ]
  }
  JSON
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/ai_video")!)
request.httpMethod = "POST"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = """
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": true,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "refs": [
    {
      "asset_id": null,
      "url": null,
      "inline_data": null
    }
  ]
}
""".data(using: .utf8)
let (data, _) = try await URLSession.shared.data(for: request)
print(String(data: data, encoding: .utf8) ?? "")

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://openapi.visionstory.ai/api/v1/ai_video");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var payload = """
{
  "client_request_id": "client_request_a1b2c3d4e5f6",
  "model_id": "seedance-2.0",
  "prompt": "string",
  "duration_sec": 10,
  "aspect_ratio": "string",
  "resolution": "string",
  "generate_audio": true,
  "first_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "end_frame": {
    "asset_id": "7241058823145623552",
    "url": "https://cdn.visionstory.ai/example.png",
    "inline_data": null
  },
  "refs": [
    {
      "asset_id": null,
      "url": null,
      "inline_data": null
    }
  ]
}
""";
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "video_id": "7241059991822401536",
    "status": "queued",
    "cost_credit": 0
  },
  "message": "success",
  "server_time": "2026-01-01T00:00:00Z"
}