Quickstart Guide

Get up and running with the Pipevideo API in five steps: sign up, create an API key, add credits, submit your first video generation, and poll for the result.

Create an account at the Pipevideo dashboard:

Production: https://app.pipevideo.com
Local development: http://localhost:3000

Sign in with your preferred provider (email, Google, etc.), then create or join an organization. All API keys and usage are scoped to your organization.

2. Get your API key

Go to Keys in the dashboard (or navigate to /keys).
Click Create Key.
Copy the key immediately — it is shown only once.

Your API key looks like pv_.... Use it in the Authorization header for all API requests:

Authorization: Bearer pv_your_api_key_here

3. Add credits

Video generation consumes credits from your organization balance.

Go to Billing in the dashboard (or navigate to /billing).
Click Add funds.
Complete checkout via Stripe.

Credits are charged when you submit a generation request. Failed generations are automatically refunded. Check your balance with GET /v1/usage.

4. Make your first generation

Submit a video generation request with POST /v1/video/generations:

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"
  }'

Response:

{
  "id": "gen_abc123xyz",
  "status": "pending",
  "created_at": 1709827200
}

Save the id — you'll use it to poll for the result.

For local development, use http://localhost:3001 instead of https://api.pipevideo.co. List available models with GET /v1/models.

5. Poll for the result

Video generation is asynchronous. Poll GET /v1/video/generations/{id} until the status is completed or failed:

curl https://api.pipevideo.co/v1/video/generations/gen_abc123xyz \
  -H "Authorization: Bearer pv_your_api_key"

Response (in progress):

{
  "id": "gen_abc123xyz",
  "status": "processing",
  "output_url": null,
  "cost_cents": null,
  "latency_ms": null,
  "error_message": null,
  "created_at": 1709827200,
  "completed_at": null
}

Response (completed):

{
  "id": "gen_abc123xyz",
  "status": "completed",
  "output_url": "https://storage.example.com/videos/abc123.mp4",
  "cost_cents": 50,
  "latency_ms": 12000,
  "error_message": null,
  "created_at": 1709827200,
  "completed_at": 1709827212
}

When status is completed, use output_url to download your video. If status is failed, check error_message for details.

Example polling script

async function waitForGeneration(apiKey, generationId) {
  const baseUrl = "https://api.pipevideo.co";
  const headers = {
    Authorization: `Bearer ${apiKey}`,
  };

  while (true) {
    const res = await fetch(
      `${baseUrl}/v1/video/generations/${generationId}`,
      { headers }
    );
    const data = await res.json();

    if (data.status === "completed") {
      return data.output_url;
    }
    if (data.status === "failed") {
      throw new Error(data.error_message || "Generation failed");
    }

    await new Promise((r) => setTimeout(r, 2000)); // Poll every 2 seconds
  }
}

Next steps

Browse Models to see available models and pricing.
Check Usage for your credit balance and request history (requires sign-in).