Build video at GPU-fleet scale.

02 / Identity

Bearer tokens & organization scopes

Create scoped API keys in VidTensor AI Studio. Send the key in the Authorization header; never place it in a URL, browser bundle, source repository, or client-side application. Rotate keys regularly and use separate keys for production and staging.

# Organization-scoped credential; keep it in a secret manager
Authorization: Bearer vt_live_YOUR_ORGANIZATION_KEY
Content-Type: application/json
User-Agent: vidtensor-sdk/2.4

Use batches:write to submit or cancel workloads and batches:read to inspect shards. A key is restricted to its owning organization and billing account. The credential string above is an instructional format, not a usable key.

03 / REST API

Batch render API

All endpoints use the versioned base URL, return JSON, and include a request identifier in X-Request-Id. Mutating requests should include an idempotency key so network retries do not create duplicate work.

Create a video-render batch. A 202 Accepted confirms validation and queue admission; it does not indicate that rendering has completed.

curl https://api.vidtensor.xyz/v1/batches/video-render \
  -X POST \
  -H "Authorization: Bearer $VIDTENSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-catalog-2026-11-10-001" \
  -d '{
    "model_pipeline": "VidTensor-Wan2.1-14B-FP8",
    "resolution": "1080p",
    "micro_batch_window_sec": 600,
    "worker_engine": "pt_aten_worker_v2.4",
    "target_vram_profile": "consumer_12gb_24gb",
    "input_manifest_uri": "s3://vidtensor-production/catalog/manifest.jsonl",
    "webhook_url": "https://studio-ingest.vidtensor.xyz/webhook",
    "idempotency_key": "sku-catalog-2026-11-10-001"
  }'

import os
import requests

response = requests.post(
    "https://api.vidtensor.xyz/v1/batches/video-render",
    headers={"Authorization": f"Bearer {os.environ['VIDTENSOR_API_KEY']}"},
    json={
        "model_pipeline": "VidTensor-Wan2.1-14B-FP8",
        "resolution": "1080p",
        "micro_batch_window_sec": 600,
        "worker_engine": "pt_aten_worker_v2.4",
        "target_vram_profile": "consumer_12gb_24gb",
        "input_manifest_uri": "s3://vidtensor-production/catalog/manifest.jsonl",
        "webhook_url": "https://studio-ingest.vidtensor.xyz/webhook",
        "idempotency_key": "sku-catalog-2026-11-10-001",
    }, timeout=30,
)
response.raise_for_status()
print(response.json()["batch_id"])

const response = await fetch("https://api.vidtensor.xyz/v1/batches/video-render", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIDTENSOR_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "sku-catalog-2026-11-10-001",
  },
  body: JSON.stringify({
    model_pipeline: "VidTensor-Wan2.1-14B-FP8",
    resolution: "1080p",
    micro_batch_window_sec: 600,
    worker_engine: "pt_aten_worker_v2.4",
    target_vram_profile: "consumer_12gb_24gb",
    input_manifest_uri: "s3://vidtensor-production/catalog/manifest.jsonl",
    webhook_url: "https://studio-ingest.vidtensor.xyz/webhook",
    idempotency_key: "sku-catalog-2026-11-10-001",
  }),
});
if (!response.ok) throw new Error(`VidTensor: ${response.status}`);
const batch = await response.json();

202 Accepted

{
  "batch_id": "bch_01J9VT8X4M2K7Q9R5N",
  "status": "queued",
  "total_shards": 24,
  "estimated_credits": 480,
  "stateless_checkpoint_mode": "per_chunk_atomic",
  "created_at": "2026-11-10T12:00:00Z",
  "request_id": "req_01J9VT8Y8K6P3A2M"
}

Manifest rows are validated before dispatch. Each row should contain a stable item_id, source assets, and generation parameters. Credit estimates are estimates; final usage is reported with the completed batch.

Read paginated per-shard state for a batch (shown below with ?limit=3). Progress is reported per 10-minute stateless micro-batch; 64-character SHA-256 checkpoint hashes identify the last atomically committed work unit. When has_more is true, pass cursor=next_cursor to retrieve the next page.

{
  "batch_id": "bch_01J9VT8X4M2K7Q9R5N",
  "status": "running",
  "total_shards": 24, "completed_shards": 17,
  "has_more": true, "next_cursor": "shd_03",
  "shards": [
    {
      "shard_id": "shd_001", "status": "running",
      "gpu_node": "RTX 3080 Ti 12GB", "progress": 0.74,
      "aten_kernel_fps": 18.6,
      "checkpoint_sha256": "4de39c7b0a4f8912c7e6255f5d3b6a18c32f114d9a8b7c6d5e4f3a2b1c0d9e8f",
      "preemption_rescheduled_count": 1
    },
    { "shard_id": "shd_002", "status": "completed", "gpu_node": "RTX 4070 12GB", "progress": 1, "aten_kernel_fps": 21.3, "checkpoint_sha256": "8f0458ce212db819fe4a6802c12ad1778f2bf0137c6d5e4f3a2b1c0d9e8f7a6b", "preemption_rescheduled_count": 0 },
    { "shard_id": "shd_003", "status": "completed", "gpu_node": "RTX 4090 24GB", "progress": 1, "aten_kernel_fps": 32.8, "checkpoint_sha256": "df911c632db3c01bda7e3d8575f4bb1938c012aa1b2c3d4e5f6a7b8c9d0e1f2a", "preemption_rescheduled_count": 0 }
  ],
  "output_mux_uri": "s3://vidtensor-production/outputs/bch_01J9VT8X4M2K7Q9R5N/final.mp4"
}

This endpoint returns paginated shard records (3 shards shown per page above; pass cursor=shd_03 while has_more is true). Poll at a measured interval or subscribe to shard.progress webhook events; respect the organization RPM limits below.

Request cancellation for queued or running work. Cancellation is asynchronous: already committed shards remain available, while in-flight work is stopped at a safe checkpoint boundary. Completed batches cannot be cancelled.

curl https://api.vidtensor.xyz/v1/batches/bch_01J9VT8X4M2K7Q9R5N/cancel \
  -X POST \
  -H "Authorization: Bearer $VIDTENSOR_API_KEY" \
  -H "Idempotency-Key: cancel-bch_01J9VT8X4M2K7Q9R5N"

Response: { "batch_id": "bch_01J9VT8X4M2K7Q9R5N", "status": "cancelling" }

04 / Event delivery

Webhook signature verification

VidTensor signs the canonical payload timestamp + "." + raw_body using HMAC-SHA256. The X-VidTensor-Signature-256 header has the format sha256=<hex digest>; X-VidTensor-Timestamp is a Unix timestamp in seconds. Concatenate the timestamp string, a literal period (.), and the unmodified raw request body bytes before computing the HMAC-SHA256 digest. Reject requests outside a five-minute clock-skew window and compare signatures in constant time.

import hashlib
import hmac
import os
import time
from flask import Flask, abort, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["VIDTENSOR_WEBHOOK_SECRET"].encode()

@app.post("/events")
def receive_event():
    raw = request.get_data()
    timestamp = request.headers.get("X-VidTensor-Timestamp", "")
    supplied = request.headers.get("X-VidTensor-Signature-256", "")
    try:
        sent_at = int(timestamp)
    except ValueError:
        abort(400)
    if abs(time.time() - sent_at) > 300:
        abort(401)
    signed_payload = timestamp.encode() + b"." + raw
    digest = hmac.new(WEBHOOK_SECRET, signed_payload, hashlib.sha256).hexdigest()
    expected = "sha256=" + digest
    if not hmac.compare_digest(expected, supplied):
        abort(401)
    event = request.get_json()
    # Persist event_id before acknowledging to make delivery idempotent.
    return {"received": True, "event_id": event["id"]}, 200

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = Buffer.from(process.env.VIDTENSOR_WEBHOOK_SECRET);

app.post("/events", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-VidTensor-Timestamp") ?? "";
  const supplied = req.header("X-VidTensor-Signature-256") ?? "";
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.sendStatus(401);
  }
  const digest = crypto.createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(timestamp + "."), req.body]))
    .digest("hex");
  const expected = Buffer.from(`sha256=${digest}`);
  const actual = Buffer.from(supplied);
  if (actual.length !== expected.length || !crypto.timingSafeEqual(actual, expected)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  return res.status(200).json({ received: true, event_id: event.id });
});

{ "id": "evt_01J9VV2Q5F", "type": "batch.completed", "created_at": "2026-11-10T12:42:19Z", "data": { "batch_id": "bch_01J9VT8X4M2K7Q9R5N", "status": "completed", "output_mux_uri": "s3://vidtensor-production/outputs/bch_01J9VT8X4M2K7Q9R5N/final.mp4" } }

05 / Official SDK

Python SDK · vidtensor.BatchClient

Install the official client with pip install --extra-index-url https://pkg.vidtensor.xyz/simple/ vidtensor-sdk. Both clients use the same API contract. Use async submission for high-volume catalogs or multilingual episodic content; consume checkpoint updates as they arrive and download the assembled output when the batch completes.

pip install --extra-index-url https://pkg.vidtensor.xyz/simple/ vidtensor-sdk

import asyncio
import os
from vidtensor import BatchClient, AsyncBatchClient

API_KEY = os.environ["VIDTENSOR_API_KEY"]
MANIFEST = "s3://vidtensor-production/series/season-04/manifest.jsonl"

# Synchronous: submit and follow a small catalog batch.
with BatchClient(api_key=API_KEY) as client:
    batch = client.batches.create(
        model_pipeline="ReelSync-LipDub-v3",
        resolution="1080p",
        input_manifest_uri=MANIFEST,
        target_vram_profile="consumer_12gb_24gb",
        micro_batch_window_sec=600,
        webhook_url="https://hooks.vidtensor.xyz/events",
        idempotency_key="series-s04-episode-pack-001",
    )
    for update in client.batches.watch_shards(batch.id, poll_interval=15):
        print(update.shard_id, update.status, update.progress,
              update.checkpoint_sha256)
    asset = client.batches.download_output(batch.id, "./renders/season-04.mp4")
    print("Assembled:", asset.path)

# Asynchronous: dispatch a thousand cross-border SKU clips concurrently.
async def render_catalog():
    async with AsyncBatchClient(api_key=API_KEY) as client:
        batch = await client.batches.create(
            model_pipeline="VidTensor-Wan2.1-14B-FP8",
            resolution="1080p",
            input_manifest_uri="s3://vidtensor-production/catalog/sku-manifest.jsonl",
            target_vram_profile="consumer_12gb_24gb",
            micro_batch_window_sec=600,
            webhook_url="https://studio-ingest.vidtensor.xyz/webhook",
            idempotency_key="catalog-2026-11-10-global-001",
        )
        async for shard in client.batches.watch_shards(batch.id, poll_interval=20):
            print(f"{shard.shard_id}: {shard.progress:.0%} on {shard.gpu_node}; "
                  f"checkpoint={shard.checkpoint_sha256}")
        result = await client.batches.download_output(
            batch.id, "./renders/catalog-complete.mp4"
        )
        print("Muxed output:", result.path)

asyncio.run(render_catalog())

For very large manifests, submit one batch per logical catalog or episode group. Keep concurrency bounded by your plan queue limit. The SDK does not embed or persist credentials unless your application explicitly configures a credential provider.

06 / Command line

vidtensor-cli · Batch Dispatcher

Use the CLI for repeatable dispatch, inspection, cancellation, and CI jobs. Configure VIDTENSOR_API_KEY through your environment or secret manager.

# Submit a manifest-driven batch
export VIDTENSOR_API_KEY=vt_live_YOUR_ORGANIZATION_KEY
vidtensor-cli batches create \
  --manifest s3://vidtensor-production/catalog/manifest.jsonl \
  --pipeline VidTensor-Wan2.1-14B-FP8 \
  --resolution 1080p \
  --vram-profile consumer_12gb_24gb \
  --window-sec 600 \
  --idempotency-key catalog-2026-11-10-global-001

# Follow live shard state and retrieve the merged output
vidtensor-cli batches shards bch_01J9VT8X4M2K7Q9R5N --watch --interval 15
vidtensor-cli batches output bch_01J9VT8X4M2K7Q9R5N --download ./renders/final.mp4

# Stop work at the next safe checkpoint boundary
vidtensor-cli batches cancel bch_01J9VT8X4M2K7Q9R5N

07 / Production reference

Error code dictionary & rate limits

Errors return a stable machine-readable code, a concise message, and a request identifier. Retry transient responses with exponential backoff and jitter; do not retry validation failures without changing the request.

Rate limits apply per organization and endpoint family. Responses include Retry-After, X-RateLimit-Limit, and X-RateLimit-Remaining. Plan limits shown here are documentation values; contracted Enterprise entitlements are defined by the organization agreement.