---
title: Sandbox
description: The Clipia API sandbox — clipia_test_* keys run the full submit → status → result cycle with no credits charged and return a sample result.
---

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.

```http
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

<Callout type="info" title="No credits are charged">
The sandbox is built to debug your code: `submit → status → result`, webhooks, and signature verification. A `clipia_test_*` key never touches your balance — no real credits are reserved or charged.
</Callout>

<Tabs items={['cURL', 'TypeScript', 'Python']}>
<Tab value="cURL">

```bash
# 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" } }'
```

</Tab>
<Tab value="TypeScript">

```ts
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"
```

</Tab>
<Tab value="Python">

```python
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"
```

</Tab>
</Tabs>

```json
{
  "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
}
```

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

```json
{
  "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 }`.

<Callout type="info" title="Why sample assets">
Sandbox sample assets are fixed and identical for every request of a given type. They exist to test your code (response parsing, polling, webhook handling), not to judge generation quality — a live `clipia_live_…` key returns the real image or video.
</Callout>