Sandbox

The sandbox (test mode) lets you debug your integration — submit → status → result, polling, webhooks, and signature verification — without spending credits and without touching real generation. Any key with the clipia_test_… prefix runs in this mode: submit instantly returns a deterministic mock result backed by a fixed sample asset.

How to enable it

1. In your dashboard (Developer Console → API Keys), flip the environment toggle to "Test" when creating a key.
2. The resulting key has the clipia_test_… prefix. Use it exactly like a live key — in any of the supported headers.

Authorization: Bearer clipia_test_xxxxxxxxxxxxxxxxxxxxxx

Test and live keys are independent: to switch to real generation, replace the key with clipia_live_… — no code changes needed.

Behaviour

When you call with a clipia_test_… key:

• No credits are charged — your balance is untouched, and no live balance is required for the sandbox.
• Real generation never runs — the request does not enter the queue.
• The result is ready instantly — submit returns status: COMPLETED straight away, skipping IN_QUEUE/IN_PROGRESS, with queue_position: 0.
• Output is a fixed sample asset on media.clipia.ai: an image for image models, a video for video models.
• cost in the response is the computed price (what the operation would cost on a live key), but it is not charged.
• Webhooks fire — if you pass a webhook_url, delivery uses the same signed mechanism (HMAC-SHA256, X-Clipia-Signature header) as production. This lets you test your handler and signature check.
• Limits and idempotency apply as usual: the RPM limit and Idempotency-Key behave just like in live mode.

Example

# Submit with a test key — result is COMPLETED immediately
curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer $CLIPIA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'

import { Clipia } from "clipia-ai";

// A clipia_test_* key returns COMPLETED right away
const clipia = new Clipia({ apiKey: process.env.CLIPIA_TEST_KEY });

const result = await clipia.models.submit("nano-banana-2", {
  input: { prompt: "a sunset over mountains, cinematic" },
});

console.log(result.status); // "COMPLETED"

import os
from clipia import Clipia

# A clipia_test_* key returns COMPLETED right away
clipia = Clipia(api_key=os.environ["CLIPIA_TEST_KEY"])

result = clipia.models.submit(
    "nano-banana-2",
    input={"prompt": "a sunset over mountains, cinematic"},
)

print(result.status)  # "COMPLETED"

{
  "request_id": "9c2f7a10-3e44-4b1a-bb9d-77e5c0a1d2e3",
  "status": "COMPLETED",
  "queue_position": 0,
  "status_url":   "https://api.clipia.ai/v1/requests/9c2f7a10-.../status",
  "response_url": "https://api.clipia.ai/v1/requests/9c2f7a10-...",
  "cost": 12
}

# Result — fetch the sample output
curl https://api.clipia.ai/v1/requests/9c2f7a10-... \
  -H "Authorization: Bearer $CLIPIA_TEST_KEY"

{
  "request_id": "9c2f7a10-...",
  "status": "COMPLETED",
  "model": "nano-banana-2",
  "output": {
    "images": [
      { "url": "https://media.clipia.ai/sandbox/sample-image.png", "width": 1024, "height": 1024 }
    ]
  },
  "cost": 12,
  "created_at": "2026-06-02T12:00:00Z",
  "completed_at": "2026-06-02T12:00:00Z"
}

For video models, output contains video: { url: "https://media.clipia.ai/sandbox/sample-video.mp4", width, height, duration }.