Video Generation Guide

This guide explains how video generation works end-to-end: creating a request, polling for status, receiving webhooks, and handling errors.

Flow overview

Video generation is asynchronous. The flow has three parts:

1. Create — Submit a generation request with POST /v1/video/generations. You receive an id and initial status: "pending".
2. Poll — Call GET /v1/video/generations/{id} repeatedly until status is completed or failed.
3. Webhook (optional) — Configure a webhook endpoint to receive video.generation.completed events when generations finish, so you don't need to poll.

Create: POST /v1/video/generations

Submit a video generation request. The API validates your model, provider, and balance, then queues the job.

Request body

*Either model or models (non-empty array) is required.

Additional parameters may be passed and are forwarded to the provider when supported. Provider-specific parameter names (e.g. aspect_ratio vs aspectRatio) are normalized internally.

Example request

curl -X POST https://api.pipevideo.co/v1/video/generations \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A cat walking on a beach at sunset",
    "aspectRatio": "16:9",
    "duration": 5
  }'

Example response

{
  "id": "gen_abc123xyz",
  "status": "pending",
  "model": "google/veo-3.1",
  "created_at": 1709827200
}

Save the id — you use it to poll for the result or correlate with webhook events. The model field shows the initial model (first in the list when using models). The final model used is returned in the poll response.

Model fallbacks

Pass models (array) instead of model to enable automatic failover. If the primary model errors (downtime, rate-limit, moderation, context length), Pipevideo tries the next model in the list until one succeeds or the list is exhausted.

curl -X POST https://api.pipevideo.co/v1/video/generations \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["google/veo-3.1", "kling/3.0-pro", "wan/2.5"],
    "prompt": "A cat walking on a beach at sunset",
    "aspectRatio": "16:9",
    "duration": 5
  }'

Billing is based on the model actually used. The model field in the poll response indicates which model completed the generation.

Provider routing

Control which provider handles your request using the provider object. When omitted, Pipevideo selects the lowest-price eligible route automatically.

Prefer a specific provider:

curl -X POST https://api.pipevideo.co/v1/video/generations \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A cat walking on a beach at sunset",
    "provider": {
      "order": ["fal"]
    }
  }'

Set a cost cap:

curl -X POST https://api.pipevideo.co/v1/video/generations \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A cat walking on a beach at sunset",
    "provider": {
      "order": ["fal", "replicate"],
      "max_price": {
        "per_request_cents": 500
      }
    }
  }'

Available provider slugs: fal, replicate. The vercel-gateway provider is used internally and is not user-selectable.

Poll: GET /v1/video/generations/{id}

Retrieve the current status and result of a generation. Poll this endpoint until status is completed or failed.

Response fields

Polling recommendations

• Interval: Poll every 2–5 seconds. Video generation typically takes 30 seconds to several minutes.
• Timeout: Stop polling after 10–15 minutes. If still pending or processing, treat as timed out and check error_message or webhook for final status.
• Webhooks: For production, prefer webhooks over polling to avoid unnecessary requests and get immediate notifications.

Webhooks

When a generation finishes (success or failure), Pipevideo sends a video.generation.completed webhook to your configured endpoint. This lets you avoid polling.

See Webhooks for setup, payload schema, signature verification, and retry behavior.

Status transitions

Generations move through these states:

pending → processing → completed
                   → failed

Transitions are one-way. A generation never moves from completed or failed back to an earlier state.

Error handling

API errors (create / get)

Generation failures (status: "failed")

When a generation fails, error_message (or the webhook errorMessage) explains the cause. Common cases:

Failed generations are automatically refunded. Your credit balance is restored.

Webhook verification errors (provider callbacks)

Pipevideo receives callbacks from providers (fal, Replicate) to know when jobs finish. These are internal; you do not call them. If verification fails, Pipevideo returns 401 or 503 to the provider. Your generation may eventually time out and be marked failed with a refund.

Parameters by provider

Parameters are passed through to the underlying provider. Naming may differ:

Model capabilities (supported aspect ratios, max duration) vary. Check the model details via GET /v1/models.

Next steps

• Quickstart — Make your first video generation.
• Webhooks — Configure webhooks for real-time completion notifications.
• Models — Browse available models and pricing.