AI Video/Get AI video status

Get AI video status

GET/api/v1/ai_video

Get one task by video_id, or up to 20 at once with video_ids (comma-separated). Status is queued, creating, created, or failed; poll every 5-10 seconds. Failed tasks carry an error object and cost_credit=0 (credits auto-refunded).

Beta: available to allowlisted API keys; standard per-key rate limits apply.

Query parameters

video_idstring | nullOptional

Id of a single task to fetch, as returned by POST /api/v1/ai_video. Provide either video_id or video_ids.

video_idsstring | nullOptional

Comma-separated task ids for a batch fetch (up to 20), e.g. 101,102,103. Provide either video_ids or video_id.

Headers

X-API-KeystringRequired

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

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)

Option 1 — Ai Video

video_idstringRequired

Unique identifier of the video task.

model_idstringRequired

Model used to generate this video; see GET /api/v1/ai_video/models.

statusstringRequired

Current task status: queued (waiting), creating (rendering), created (ready), or failed.

video_urlstring | nullOptional

Download URL of the generated video; present once status is created.

cover_urlstring | nullOptional

URL of the video's cover/thumbnail image when available.

duration_secnumberOptionalDefault 0

Length of the generated video in seconds; 0 until known.

resolutionstringOptionalDefault ""

Output resolution of the generated video (e.g. 720p, 1080p); empty until known.

aspect_ratiostringOptionalDefault ""

Output aspect ratio of the generated video (e.g. 16:9, 9:16); empty until known.

cost_creditintegerOptionalDefault 0

Credits charged for this task; 0 when it failed (the charge is auto-refunded).

created_atintegerOptionalDefault 0

Unix timestamp (seconds) when the task was created.

errorAiVideoErrorDto | nullOptional

Failure detail; present only when status is failed.

Show 2 propertiesHide 2 properties

codeintegerRequired

Numeric code identifying why generation failed.

messagestringRequired

Human-readable explanation of the failure.

Option 2 — Ai Videos Batch

videosarray of AiVideoDtoRequired

Requested video tasks that exist and belong to this account (missing ids are omitted).

Show 11 propertiesHide 11 properties

video_idstringRequired

Unique identifier of the video task.

model_idstringRequired

Model used to generate this video; see GET /api/v1/ai_video/models.

statusstringRequired

Current task status: queued (waiting), creating (rendering), created (ready), or failed.

video_urlstring | nullOptional

Download URL of the generated video; present once status is created.

cover_urlstring | nullOptional

URL of the video's cover/thumbnail image when available.

duration_secnumberOptionalDefault 0

Length of the generated video in seconds; 0 until known.

resolutionstringOptionalDefault ""

Output resolution of the generated video (e.g. 720p, 1080p); empty until known.

aspect_ratiostringOptionalDefault ""

Output aspect ratio of the generated video (e.g. 16:9, 9:16); empty until known.

cost_creditintegerOptionalDefault 0

Credits charged for this task; 0 when it failed (the charge is auto-refunded).

created_atintegerOptionalDefault 0

Unix timestamp (seconds) when the task was created.

errorAiVideoErrorDto | nullOptional

Failure detail; present only when status is failed.

Show 2 propertiesHide 2 properties

codeintegerRequired

Numeric code identifying why generation failed.

messagestringRequired

Human-readable explanation of the failure.

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 GET 'https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx'

import requests

url = "https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
}
response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx", {
  method: "GET",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
  },
});
const data = await response.json();
console.log(data);

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx", nil)
	req.Header.Set("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
	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?video_id=xxxx&video_ids=xxxx"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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?video_id=xxxx&video_ids=xxxx");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

require "net/http"
require "uri"

uri = URI("https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request["X-API-Key"] = "sk-vs-xxxxxxxxxxxxxxxxxxx"
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx")!)
request.httpMethod = "GET"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
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.Get, "https://openapi.visionstory.ai/api/v1/ai_video?video_id=xxxx&video_ids=xxxx");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "video_id": "7241059991822401536",
    "model_id": "seedance-2.0",
    "status": "completed",
    "video_url": "https://cdn.visionstory.ai/example.mp4",
    "cover_url": "https://cdn.visionstory.ai/example.png",
    "duration_sec": 0,
    "resolution": "",
    "aspect_ratio": "",
    "cost_credit": 0,
    "created_at": 0,
    "error": null
  },
  "message": "success",
  "server_time": "2026-01-01T00:00:00Z"
}