API Reference
Integration Guides

Playground

Use the dashboard playground to exercise real /v1 routes with a selected API key.

How it works

  • The playground is a dashboard tool under /studio/api/playground.
  • It requires a logged-in dashboard session and a selected stored API key.
  • Calls are proxied to public /v1/* routes only, not /api/developer/*.
  • The selected API key is injected server-side, so you can inspect real responses without copying raw secrets into the browser.

Good default workflow

Create a scoped key, test one endpoint in the playground, then confirm the result in GET/v1/usage or the Studio usage page before wiring that call into your app.

Request shaping

The proxy accepts a method, a /v1/* endpoint, optional headers, a body, and the selected apiKeyId.

POST/api/developer/playground/test
Auth: Dashboard JWT/sessionBilling: Free for the proxy itself; upstream /v1 route may consume API callsBehavior: Proxies one selected /v1 request with a stored API key
JSON request bodyhttp
POST /api/developer/playground/test
Authorization: Bearer <dashboard_jwt>
Content-Type: application/json

{
  "apiKeyId": "c7b29096-897a-43da-9623-8185548fd417",
  "method": "POST",
  "endpoint": "/v1/music/songs",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "prompt": "Warm indie pop with female vocal hooks",
    "lyrics": "You found me in the static..."
  }
}
Multipart upload requesthttp
POST /api/developer/playground/test
Authorization: Bearer <dashboard_jwt>
Content-Type: multipart/form-data

apiKeyId=<uuid>
method=POST
endpoint=/v1/music/uploads
headers={"Content-Type":"multipart/form-data"}
file=@./reference.wav
body={"purpose":"track-edit source"}

Automatic behavior

For POST requests to music, speech, and sound-effects endpoints, the playground injects an Idempotency-Key when you do not provide one. That makes it safer to retry demos without accidentally creating duplicate jobs.

What you get back

The playground response includes the upstream URL, headers, status code, latency, and the original response body from the API gateway.

Playground proxy responsejson
{
  "success": true,
  "data": {
    "statusCode": 202,
    "latencyMs": 184,
    "upstreamUrl": "http://localhost:4000/v1/music/songs",
    "headers": {
      "content-type": "application/json; charset=utf-8",
      "x-api-calls-remaining": "154"
    },
    "body": {
      "success": true,
      "data": {
        "request_id": "590b41ed-bf0f-42cf-bad9-32568c09475a",
        "status": "accepted"
      }
    }
  }
}
Async visibility

If an endpoint returns 202, use the returned request_id with polling or webhooks.

Header inspection

Response headers let you verify remaining API calls, content type, and retry signals.

Usage logging

Successful playground calls still hit the real API, so usage and logs update as if your integration sent them directly.

Common gotchas

  • API keys created before reversible encryption support cannot be used in the playground. Create a fresh key if the proxy rejects an older one.
  • The playground has its own dashboard rate limit bucket, separate from the public per-service /v1 rate limits.
  • Multipart requests must use the file picker; manually forcing JSON for upload routes will fail validation upstream.
  • Dashboard endpoints like GET/api/developer/billing are not part of the API-key playground surface.
Was this page helpful?
Previous
Async JobsNext