Video Generation

POST/v1/run

Generate videos using AI models. Video generation is asynchronous — you submit a request and poll for results.

For each asynchronous video job, you may set webhook_url on that request or register an organization Model Webhook. Synchronous model calls and LLM calls do not support task callbacks; if they contain this field, SandBase ignores it and schedules no callback. See Webhooks.

Parameters

Parameter	Type	Required	Description
model	string	✅	Model name (e.g. kling/v2, wan/2.1)
prompt	string	✅	Text description of the video
duration	number	❌	Video duration in seconds
image_url	string	❌	Reference image for image-to-video
webhook_url	string	❌	Public HTTPS callback URL for this async task only

Async Flow

# 1. Submit generation request
response = client.post("/v1/run", json={
    "model": "kling/v2",
    "prompt": "A cat playing piano",
    "duration": 5,
    "webhook_url": "https://hooks.example.com/sandbase/task?token=opaque-token"
})
generation_id = response.json()["id"]

# 2. SandBase posts the terminal event to webhook_url.
# You may still poll the existing result endpoint as a fallback.
import time
while True:
    result = client.get(f"/v1/run/{generation_id}").json()
    if result["status"] == "completed":
        print(result["outputs"][0]["url"])
        break
    time.sleep(5)

The task callback receives completed, failed, or timeout with X-Event-ID. Delivery is at-least-once; deduplicate by that ID and return 2xx quickly. The URL must be public HTTPS. When webhook_url is present, it is the only callback target for this task and registered organization Model Webhooks are skipped; failures retry the same task URL without fallback. Per-task callbacks do not include X-Signature; omit webhook_url and use an organization Model Webhook when HMAC verification is required.

Available Models

Model	Provider	Duration	Price
kling/v2	Kuaishou	5–10s	$0.10–$0.30
wan/2.1	Alibaba	5s	$0.05
runway/gen3	Runway	4–16s	$0.25–$1.00

→ Browse all video models