مرجع الواجهة البرمجية أدناه بالإنجليزية، لأن أسماء الحقول والأكواد بالإنجليزية.

Getting started

One key, one machine endpoint, every render C2PA-sealed. Keys are minted on the Developers screen in the studio — the admin console has no route that creates one.

GET/api/healthz

Health & engine status

Reachability of the gateway and each worker behind it. This claimed to return a model name, a CUDA device and a sample rate; it returns none of those.

curl

curl https://api.regalabs.dev/api/healthz

response

{
  "ok": true,
  "store": "postgres",
  "queue": "redis",
  "hmac": true,
  "engine": { "ok": true, "status": 200 },
  "jiyan": { "ok": true, "status": 200 },
  "wene":  { "ok": true, "status": 200 }
}

Authentication

One header, one key. Keys are created on the Developers screen in the studio and carry their own credit balance, moved there from your account — a key spends its own credits and never touches your interactive balance.

Parameter	Type	Required	Description
Authorization	Bearer rega_live_…	yes	The key. A malformed or revoked key is 401 before anything else runs.
Idempotency-Key	string ≤ 160	yes	Required in production on every paid generation. Replaying the same key returns the first response instead of charging twice.
Content-Type	application/json	yes	Every machine request carries a JSON body.

What a key can reach

A key authenticates POST /api/v1/generate and nothing else. Every other route on this page is a studio route: it authenticates with the session cookie, so it answers a browser signed into the studio rather than a server holding a key.

POST/api/v1/generate

Generate — the machine API

The only route an API key authenticates. Spends that key's own credits, never your interactive balance.

Parameter	Type	Required	Description
kind	image \| video	yes	What to make. The provider must support it.
providerId	string	yes	A public generation provider. Ask an admin which are enabled for your account.
prompt	string	yes	What to generate.
durationSeconds	number	no	Video only. Billed by the second at 250 credits a minute — a ten-second clip costs ten seconds, not a minute.

curl

curl -X POST https://api.regalabs.dev/api/v1/generate \
  -H "Authorization: Bearer rega_live_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "providerId": "your-provider",
    "prompt": "a rooftop in Hewlêr at dusk"
  }'

202 means submitted, not finished

A provider that works asynchronously answers 202 with a job id. The credits are already spent at that point.

Error contract

Errors always carry a machine-readable code and a human message.

error codes

{
  "SIGN_IN_REQUIRED":          "Identity-bound operations need a session.",
  "ACCOUNT_BANNED":            "Account is no longer active.",
  "STUDIO_CLOSED":             "The studio is closed for maintenance.",
  "VOICE_CLONE_LIMIT_EXCEEDED": "One clone per account — deepfake shield.",
  "CREDITS_EXHAUSTED":         "Not enough credits for this generation.",
  "IDEMPOTENCY_KEY_REQUIRED":  "Paid generations need an Idempotency-Key header.",
  "IDEMPOTENCY_KEY_REUSED":    "That key was used for different content.",
  "COUPON_APPLIES_AT_CHECKOUT": "A percent code comes off the price, not the balance.",
  "COUPON_ALREADY_REDEEMED":   "Code already used on this account."
}

Local dev

Run npm run stack and hit http://127.0.0.1:8787/api/v1/* directly — the gateway proxies the signed inference channel for you.