API Documentation

Machine-readable references

Authentication

For authenticated endpoints, send your API key in `Authorization: Bearer <key>` or `x-api-key`. API keys are shown once when created.

Static-hosted key management is available at `/dashboard` using an API key as your primary credential.

Endpoint inventory

Checkout and first key flow

1) create checkout, 2) complete payment, 3) claim the first API key.

curl -X POST "$API_BASE/api/v1/checkout/stripe" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@company.com",
    "packageCode": "builder_600"
  }'

curl -X POST "$API_BASE/api/v1/claim/stripe" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "cs_test_...",
    "keyLabel": "Primary key"
  }'

API key lifecycle (agents and services)

Create separate keys per environment or agent for safe rotation and revocation.

curl -X POST "$API_BASE/api/v1/keys" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Agent Worker A"
  }'

curl -X GET "$API_BASE/api/v1/keys" \
  -H "Authorization: Bearer $API_KEY"

curl -X POST "$API_BASE/api/v1/keys/revoke" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyPrefix": "abcde"
  }'

const res = await fetch("${API_BASE}/api/v1/keys", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ label: "Build Agent" }),
});

const data = await res.json();
// data.apiKey is only returned once; store it securely.

Credits and media usage

Use `task` + `input` payloads for generation. Supported tasks: `image.generate` (Qwen Image), `image.edit` (Qwen Image Edit), `video.generate` (LTX2), and `audio.speak` (Qwen3 TTS).

curl -X GET "$API_BASE/api/v1/credits/balance" \
  -H "Authorization: Bearer $API_KEY"

curl -X POST "$API_BASE/api/v1/media/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: job-001" \
  -d '{
    "task": "image.generate",
    "input": {
      "prompt": "cinematic fox astronaut",
      "aspectRatio": "1:1"
    },
    "creditsToConsume": 1
  }'

curl -X POST "$API_BASE/api/v1/media/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "image.edit",
    "input": {
      "prompt": "turn this scene into a dramatic noir poster",
      "sourceImageUrl": "https://cdn.example.com/input/source.webp",
      "aspectRatio": "9:16"
    }
  }'

curl -X POST "$API_BASE/api/v1/media/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "video.generate",
    "input": {
      "prompt": "slow cinematic push-in with floating particles",
      "sourceImageUrl": "https://cdn.example.com/input/source.webp",
      "durationSeconds": 6,
      "aspectRatio": "16:9"
    }
  }'

curl -X POST "$API_BASE/api/v1/media/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "audio.speak",
    "input": {
      "text": "Welcome to the API gateway.",
      "voiceDescription": "Warm, energetic narrator with clear pacing.",
      "language": "English"
    }
  }'

Idempotency and errors

curl -X POST "$API_BASE/api/v1/media/jobs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: job-001" \
  -d '{
    "task": "image.generate",
    "input": {
      "prompt": "cinematic fox astronaut",
      "aspectRatio": "1:1"
    },
    "creditsToConsume": 1,
    "idempotencyKey": "job-001"
  }'

Send `X-Idempotency-Key` when retrying writes (`/api/v1/credits/consume`, `/api/v1/media/jobs`) to avoid duplicate debits. Error responses are JSON with `error` and optional `details`.