Video generation

This guide covers the full video generation lifecycle: creating a request, polling for status, receiving webhooks, and handling errors.

Flow overview

Video generation is asynchronous:

1. Create — POST /v1/responses returns an id and status: "queued".
2. Poll — GET /v1/responses/{id} until status is completed or failed.
3. Webhook (optional) — receive video.generation.completed events instead of polling.

Token billing

HyperFrames generations bill the orchestration LLM by token usage:

• Rates are listed per million tokens on Engines and via GET /v1/engines.
• Token usage is collected when the orchestration agent finishes composing your project.
• Credits are deducted after orchestration, before render and upload complete.
• The usage field on completed responses reflects token counts and cost_usd.

You need a positive credit balance to create a request.

Create: POST /v1/responses

Request body

Example

curl -X POST https://api.pipevideo.co/v1/responses \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonshotai/kimi-k2.5",
    "input": "A cat walking on a beach at sunset",
    "provider": { "order": ["framerate"] }
  }'

Response

{
  "id": "gen_abc123xyz",
  "object": "response",
  "status": "queued",
  "model": "moonshotai/kimi-k2.5",
  "engine": "hyperframes",
  "provider": "framerate",
  "created_at": 1709827200,
  "output": [
    {
      "type": "message",
      "id": "gen_abc123xyz_msg",
      "role": "assistant",
      "status": "in_progress",
      "content": []
    }
  ],
  "output_video_url": null
}

Poll: GET /v1/responses/{id}

Polling recommendations

• Poll every 2–5 seconds. Generation typically takes 30 seconds to several minutes.
• Stop after 10–15 minutes if still queued or in progress.
• For production, use webhooks instead of polling.

Status transitions

queued → in_progress → completed
                    → failed

Transitions are one-way.

Error handling

HTTP errors

Generation failures

Providers

Pipevideo routes generation to an external video orchestration provider. Pipevideo handles credits, organization scoping, and customer webhooks. See Provider routing and Framerate.

Next steps

• Responses API — full request/response schema
• Multimodal inputs — reference images and video
• Webhooks — push notifications for completions