Video API

Generate video clips from text or images. 104 models from $0.04/clip. Async with polling and webhooks.

Async API. Video generation is asynchronous. You submit a job and poll GET /v1/jobs/:id for the result, or use a webhook callback.

POST /v1/generations/video

Submit a video generation job. Returns a job ID for async polling.

Request body

Field	Type	Required	Description
`model`	string	Yes	Model key (e.g. `"wan-2-1-t2v"`, `"kling-2-1-std-i2v"`, `"veo-3"`). See Model Catalog.
`prompt`	string	Yes	Text description of the video to generate.
`image`	string (URL)	No	Source image for image-to-video models (`i2v`).
`duration`	number	No	Duration in seconds. Model-dependent (typically 3-10s).
`aspect_ratio`	string	No	`"16:9"`, `"9:16"`, `"1:1"`. Default varies by model.
`resolution`	string	No	`"720p"` or `"1080p"`. Default: `"720p"`.
`webhook_url`	string (URL)	No	URL to POST the result to when complete.
`confirm`	boolean	No	Set to `false` for cost estimate only. Default: `true`.

Response fields (on submit)

Field	Type	Description
`id`	string	Job ID (`job_` prefix). Use with `GET /v1/jobs/:id`.
`status`	string	`"queued"` on submit.
`estimated_cost`	object	Estimated cost (micro + display).

Response fields (on completion)

Field	Type	Description
`id`	string	Job ID.
`status`	string	`"completed"` or `"failed"`.
`url`	string	CDN URL of the generated MP4.
`cost.micro`	integer	Actual cost in microdollars.
`cost.display`	string	Human-readable cost (e.g. `"$0.048"`).
`metadata.duration`	number	Video duration in seconds.
`metadata.width`	integer	Video width in pixels.
`metadata.height`	integer	Video height in pixels.
`metadata.fps`	integer	Frames per second.

Code examples

curl

curl -X POST https://api.fairstack.ai/v1/generations/video \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2-1-t2v",
    "prompt": "A golden retriever running on a beach at sunset, slow motion"
  }'

Submit response:

{
  "id": "job_xyz789",
  "status": "queued",
  "estimated_cost": {
    "micro": 48000,
    "display": "$0.048"
  }
}

Python

from fairstack import FairStack

client = FairStack(api_key="fs_live_YOUR_KEY")

# Submit async video generation
job = client.generate.video(
    model="wan-2-1-t2v",
    prompt="A golden retriever running on a beach at sunset, slow motion"
)

# Poll for result
result = job.wait()  # blocks until complete
print(result.url)    # https://media.fairstack.ai/video/...
print(result.cost)   # $0.048

Node.js

import { FairStack } from "fairstack";

const client = new FairStack({ apiKey: "fs_live_YOUR_KEY" });

// Submit async video generation
const job = await client.generate.video({
  model: "wan-2-1-t2v",
  prompt: "A golden retriever running on a beach at sunset, slow motion",
});

// Poll for result
const result = await job.wait();
console.log(result.url);   // https://media.fairstack.ai/video/...
console.log(result.cost);  // { micro: 48000, display: "$0.048" }

Completed response

{
  "id": "job_xyz789",
  "status": "completed",
  "url": "https://media.fairstack.ai/video/.../output.mp4",
  "model": "wan-2-1-t2v",
  "modality": "video",
  "cost": {
    "micro": 48000,
    "display": "$0.048",
    "currency": "USD"
  },
  "metadata": {
    "width": 1280,
    "height": 720,
    "duration": 5,
    "fps": 24
  }
}

Cost estimation

Set confirm: false to get the exact cost without submitting the job.

curl -X POST https://api.fairstack.ai/v1/generations/video \
  -H "Authorization: Bearer $FAIRSTACK_API_KEY" \
  -d '{
    "model": "wan-2-1-t2v",
    "prompt": "test",
    "confirm": false
  }'

# Response (no video generated, no charge):
# { "estimated_cost": { "micro": 48000, "display": "$0.048" } }

Image-to-video

Many models support image-to-video generation. Include a source image URL:

{
  "model": "kling-2-1-std-i2v",
  "prompt": "Camera slowly zooms in, soft wind blowing hair",
  "image": "https://example.com/photo.jpg",
  "duration": 5,
  "aspect_ratio": "16:9"
}

Webhooks

Instead of polling, provide a webhook_url to receive a POST when the job completes:

{
  "model": "kling-2-1-std-i2v",
  "prompt": "Animate this portrait with gentle head movement",
  "image": "https://example.com/portrait.jpg",
  "webhook_url": "https://yourapp.com/hooks/fairstack"
}

The webhook payload is identical to the GET /v1/jobs/:id response.

Quality tiers

Tier	Example Model	Price	Speed	Best For
Budget	Wan 2.1 T2V	$0.04-0.06	~30s	Prototyping, social clips
Standard	Kling 2.1 Std	$0.10-0.30	~60s	Marketing, product demos
Premium	Veo 3, Runway Gen-4	$0.15-0.50	~90s	Professional, cinematic

Next steps

Video Guide -- text-to-video, image-to-video, extend, restyle
Jobs API -- poll async jobs
Video Models -- browse all 104 video models
Error Handling -- retries and idempotency

Image API Voice API