Core concepts

Organization

Your organization is the billing and access boundary. API keys, credit balance, usage history, and webhook endpoints are scoped to the organization you select in the dashboard. Switch organizations from the org switcher in the header.

API keys

API keys authenticate HTTP requests. Each key belongs to one organization and can be named, rotated, and revoked independently. Pass the key as a Bearer token:

Authorization: Bearer pv_...

See API keys for rotation and storage guidance.

Engines and orchestration models

Pipevideo separates two layers:

The model field in your request is always an orchestration model id, not an engine slug. List both engines and their supported models with GET /v1/engines.

Generation lifecycle

Video generation is asynchronous:

queued → in_progress → completed
                    → failed

1. Create — POST /v1/responses returns an id and status: "queued".
2. Process — Pipevideo runs orchestration, bills tokens, then renders and uploads the video.
3. Complete — Poll GET /v1/responses/{id} or receive a webhook.

See the video generation guide for parameters, polling intervals, and error cases.

Provider routing

Pipevideo routes generation to external video orchestration providers. You integrate with Pipevideo only; providers are selected automatically or via provider.order:

{ "provider": { "order": ["framerate"] } }

When omitted, Pipevideo uses the default provider for the requested engine. See Provider routing.

Credits and billing

Pipevideo uses pay-as-you-go credits (stored in cents). HyperFrames generations bill the orchestration LLM by token usage after the agent finishes composing your project. You need a positive balance to create a request.

• View balance and top up in Billing.
• Review consumption in Usage or via GET /v1/usage.

Multimodal prompts

Input follows the OpenAI Responses format. Content parts can include:

• input_text — your generation prompt
• input_image — reference images (HTTPS or data:image/ URIs)
• input_video — reference video clips (HTTPS or data:video/ URIs)

Use top-level instructions for system-level guidance. See Multimodal inputs.

App attribution

Optional headers identify your application for rankings and analytics (OpenRouter-compatible):

See App attribution.