Authentication

All Pipevideo API requests require authentication via an API key. This guide covers how to create keys, authenticate requests, use optional headers, rotate keys, and understand rate limits.

API key creation

1. Sign in to the Pipevideo dashboard (or localhost:3000 for local development).
2. Go to Keys in the sidebar (or navigate to /keys).
3. Click Create Key.
4. Give your key a name (e.g. "Production API Key" or "My App").
5. Copy the key immediately — it is shown only once and cannot be retrieved later.

API keys are scoped to your organization. Keys look like pv_ followed by a long hex string (e.g. pv_a1b2c3d4e5f6...).

Bearer token authentication

Include your API key in the Authorization header for every request:

Authorization: Bearer pv_your_api_key_here

Example with curl:

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 on a beach"}'

Example with JavaScript:

const response = await fetch("https://api.pipevideo.co/v1/video/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/veo-3.1",
    prompt: "A cat on a beach",
  }),
});

Requests without a valid Authorization: Bearer <key> header receive 401 Unauthorized.

X-Application-Name header

You can optionally identify your application by sending the X-Application-Name header (or X-App-Name):

X-Application-Name: my-video-app

This value is stored with each generation for usage analytics and debugging. It is truncated to 256 characters. The header is optional — omit it if you do not need application-level tracking.

Example:

curl https://api.pipevideo.co/v1/video/generations/gen_abc123 \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "X-Application-Name: my-production-app"

App attribution headers

For rankings and analytics (similar to OpenRouter app attribution), you can optionally send attribution headers. These help Pipevideo attribute usage to your app for future leaderboards and analytics.

All attribution headers are optional. Requests without them behave exactly as before. If you use a localhost URL as referer, include a title so your app can be tracked.

Example:

curl -X POST https://api.pipevideo.co/v1/video/generations \
  -H "Authorization: Bearer pv_your_api_key" \
  -H "Referer: https://my-video-app.example.com" \
  -H "X-Pipevideo-Title: My Video Generator" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/veo-3.1", "prompt": "A cat on a beach"}'

Example with JavaScript:

const response = await fetch("https://api.pipevideo.co/v1/video/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    Referer: "https://my-video-app.example.com",
    "X-Pipevideo-Title": "My Video Generator",
  },
  body: JSON.stringify({
    model: "google/veo-3.1",
    prompt: "A cat on a beach",
  }),
});

Key rotation

To rotate an API key:

1. Create a new key in the dashboard (Keys → Create Key).
2. Update your application to use the new key.
3. Revoke or delete the old key:
   • Revoke — Deactivates the key. Requests with the old key will fail with 401. You can see revoked keys in the list.
   • Delete — Permanently removes the key from the database. Use this when you no longer need any record of the key.

Revoking is useful when you want to quickly invalidate a key (e.g. suspected compromise) while keeping a record. Deleting is useful for cleanup.

Rate limits

API requests are rate-limited to 100 requests per minute per API key. The limit uses a sliding window.

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry (in seconds).

Example error response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}

To avoid hitting the limit:

• Implement exponential backoff when you receive 429 responses.
• Batch or throttle requests in high-throughput scenarios.
• Use multiple API keys (e.g. per environment or service) if you need higher aggregate throughput — each key has its own 100 req/min quota.