Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vibepeak.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Test Mode

Test mode is a free sandbox for the credit-consuming video endpoints. A test-mode API key exercises the exact same request, validation, async lifecycle, and signed-webhook surface as a live key — but it never spends credits, never runs the real generation pipeline, and instead returns a watermarked sample video. It lets you build and verify your integration — request shape, authentication, polling, webhook delivery, signature verification, and error handling — without spending anything.
Test mode is available on the two credit-consuming endpoints: Create Narrated Slideshow and Create Living Property Video. All other endpoints behave identically regardless of key type.

​
The Two-Phase Model

Like most developer platforms, VibePeak separates integration testing from output evaluation:
1

Phase 1 — Integration (free, test mode)

Use a vpk_test_ key to wire up and harden your integration end to end: building requests, handling 202 responses, polling or receiving webhooks, verifying HMAC signatures, and handling success and failure paths. This is unlimited and costs nothing.
2

Phase 2 — Output quality (a few live credits)

Once your integration is solid, switch to a vpk_live_ key and spend a small number of real credits to judge the actual video quality. Test mode never produces a real video, so output quality is always evaluated separately with live credits.

​
Key Prefixes

Every API key carries a prefix that determines its mode:
PrefixModeBehavior
vpk_live_LiveCharges credits, runs the real generation pipeline, returns your real video
vpk_test_TestCharges nothing, returns a watermarked sample, ignores real generation
A key’s mode is fixed at creation. You obtain a test-mode key from your dashboard the same way as a live key — see Authentication.

​
What Test Mode Validates

A test request runs through the identical front-half of the pipeline as a live request. Everything you need to harden your integration is exercised for real:

Authentication

Bearer token parsing, key validity, and plan checks behave exactly as in live mode.

Full input validation

Schema validation, script length and character rules, voice and avatar checks — all enforced.

SSRF protection

Image and webhook URLs are still rejected if they are non-HTTPS (webhooks) or point to private networks.

Async lifecycle

queued → processing → completed | failed, plus the Location and Retry-After headers.

Signed webhooks

The completion webhook is delivered and HMAC-signed with the same headers as live.

Error & failure paths

Simulate a failed task to exercise your error and retry handling.

​
What Test Mode Does Not Validate

Test mode never runs the real generation pipeline, so it cannot tell you anything about the quality, content, or real timing of your video. The returned clip is a fixed sample, not a render of your images or script. Always judge output quality in Phase 2 with a vpk_live_ key.
Specifically, a test request does not:
  • Charge credits or touch your credit balance
  • Call any third-party AI provider or run the video renderer
  • Count against your live concurrency limit
  • Reflect real generation time (the synthetic delay is short and configurable, not representative)

​
The test_scenario Parameter

Both credit-consuming endpoints accept an optional test_scenario field so you can drive the synthetic lifecycle down a specific path. It is honored only for test-mode keys and silently ignored for live keys, so it is safe to leave in shared request-building code.
ValueOutcome
success (default)Task completes after a short delay with a sample video
failTask fails with a sanitized, public-safe error so you can exercise your error handling
slowLike success, but completes after a noticeably longer delay so you can test polling timeouts and slow-path UX
Request body (excerpt)
{
  "test_scenario": "fail"
}
When test_scenario is fail, the task finishes with status failed and this error:
Failed test task
{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "livemode": false,
  "error": {
    "code": "TEST_MODE_SIMULATED_FAILURE",
    "message": "Simulated failure for test mode. No video was generated and no credits were used."
  }
}

​
The livemode Field

Every task-creation response and every task-status response includes a boolean livemode field. It is the single, reliable signal for whether a task is real:
  • livemode: true — created with a vpk_live_ key; real credits were spent and a real video is produced.
  • livemode: false — created with a vpk_test_ key; this is a sandbox task with a sample video.
The same livemode field is included in the webhook payload, so your webhook handler can branch on it (for example, skip downstream billing or storage for sandbox events).

​
Sample Asset Behavior

A successful test task (success or slow) completes with a fixed, watermarked sample:
Completed test task
{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "livemode": false,
  "result": {
    "video_url": "https://storage.vibepeak.ai/samples/sample-landscape.mp4",
    "cover_image_url": "https://storage.vibepeak.ai/samples/sample-cover.jpg",
    "duration_seconds": 12,
    "total_scenes": 3
  }
}
  • The clip is visibly watermarked SAMPLE and is the same for every test request — it is not a render of your images or script.
  • The sample is orientation-aware: a portrait request returns a portrait sample, otherwise a landscape one.
  • duration_seconds and total_scenes are fixed sample metadata, not a prediction of your real video.

​
Test / Live Isolation

Test and live traffic are fully isolated:
A vpk_test_ key can only read test tasks, and a vpk_live_ key can only read live tasks. Reading a task created with the other mode returns the same 404 TASK_NOT_FOUND as a task that does not exist — there is no cross-mode existence leak.
  • Sandbox tasks never consume your live concurrency limit, and live tasks are never throttled by sandbox traffic.
  • Sandbox tasks are excluded from usage and concurrency aggregation entirely.
1

Wire up with a test key

Build your request, submission, polling, and webhook handling against a vpk_test_ key with test_scenario: "success".
2

Exercise failure handling

Send test_scenario: "fail" and confirm your code handles a failed task and surfaces the error correctly.
3

Test slow paths

Send test_scenario: "slow" and confirm your polling/timeout logic and any loading UI behave well on a longer-running task.
4

Verify webhook signatures

Point webhook_url at your endpoint and confirm you verify the HMAC signature and branch on livemode.
5

Switch to live for quality

Swap to your vpk_live_ key and spend a few real credits to evaluate actual video quality.
curl -X POST https://api.vibepeak.ai/v1/real-estate/narrated-slideshow \
  -H "Authorization: Bearer vpk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      "https://example.com/property/living-room.jpg",
      "https://example.com/property/kitchen.jpg",
      "https://example.com/property/bedroom.jpg",
      "https://example.com/property/bathroom.jpg",
      "https://example.com/property/backyard.jpg",
      "https://example.com/property/exterior.jpg"
    ],
    "voice": { "voice_id": "EXAVITQu4vr4xnSDxMaL", "language": "en" },
    "script": "Welcome to this stunning home in the heart of the city. The open living area floods with natural light and flows into a modern kitchen...",
    "test_scenario": "success",
    "webhook_url": "https://yourserver.com/webhooks/vibepeak"
  }'

​
Next Steps

Authentication

Key prefixes, formats, and how to obtain them

Async Processing

The task lifecycle and polling strategy

Webhooks

Verifying signatures and handling livemode

Error Handling

Error codes and retry strategies