Get started

Authentication

Learn how to authenticate your API requests using API keys.

API key format

OyeFilmy uses bearer token authentication. API keys have two prefixes:

Prefix	Environment	Description
`of_live_`	Production	Charges credits, generates real assets. Use in production apps.
`of_test_`	Testing	Identical behaviour, marked for testing. It still charges real credits and produces real assets — there is no sandbox or free tier attached to this prefix.

Making authenticated requests

Include your API key in the Authorization header with the Bearer scheme:

curl -X GET https://api.oyefilmy.com/api/credits/balance \
  -H "Authorization: Bearer of_live_YOUR_API_KEY"

Security: Never expose your API key in client-side code or public repositories. Always call the API from a server.

Scopes

Each API key has one or more scopes that control which endpoints it can access:

Scope	Description	Endpoints
`read`	Read your generation history	GET /generate/history, GET /generate/reframe/history
`write`	Covers the whole generate family — a key with write can run any modality	POST /generate (all modalities)
`generate:image`	Run image models, including upscale and background removal	POST /generate (image models)
`generate:video`	Run video models, including video upscale	POST /generate (video models)
`generate:audio`	Run audio, music and speech models	POST /generate (audio models)
`generate:3d`	Run 3D models	POST /generate (3D models)
`billing`	Read your credit balance and plan	GET /credits/balance

Principle of least privilege: only assign the scopes your application needs — a rendering pipeline needs just generate:image and read. Note that write is a superset: it permits every generation modality, so grant a specific generate:* scope instead when you want a key limited to one kind of output. Calling an endpoint without the scope it requires returns 403 and costs no credits.

Creating API keys

API keys are created through the dashboard using JWT authentication (not through API keys themselves). This prevents key escalation attacks.

// API key management is dashboard-only
POST /api/keys        → Create a new key
GET  /api/keys        → List all keys
PATCH /api/keys/:id   → Rename a key
DELETE /api/keys/:id  → Revoke a key

Create key request:

POST /api/keys
{
  "name": "Production server",
  "scopes": ["read", "write", "generate:image", "generate:video"],
  "rateLimit": 120,   // default 120, allowed range 10–6000
  "env": "live"       // "live" (default) or "test" — sets the key prefix
}

Response: the fields are flat, not nested under a record object.

{
  "success": true,
  "key": "of_live_9f3c8a21d4b60e7f15a2c8d93b41e607af52c1d8b3e94a60",  // ← 48 hex chars, shown once
  "id": "6a770959665bfafb9493af71",
  "name": "Production server",
  "masked": "of_live_••••••••e607",
  "prefix": "of_live",
  "scopes": ["read", "write", "generate:image", "generate:video"],
  "rateLimit": 120,
  "requests": 0,
  "lastUsedAt": null,
  "revokedAt": null,
  "status": "active",
  "createdAt": "2026-08-08T11:04:00.000Z"
}

Every later response — GET /api/keys and the dashboard — returns the same fields without key, showing only masked. Only a SHA-256 hash of the secret is stored, so a lost key cannot be recovered and must be revoked and replaced. You may hold up to 20 active keys.

One-time display: The full API key secret is returned only once when created. Store it immediately in a secure location.

Rate limiting

Each API key has its own rate limit in requests per minute, chosen when you create it. The default is 120/min and the allowed range is 10–6000. A separate platform-wide ceiling of 300/min also applies. When either is exceeded, the API returns:

HTTP 429 Too Many Requests
{
  "statusCode": 429,
  "message": "Rate limit exceeded for this API key (120/min)."
}

See the full rate limits guide →

Error responses

Status	Meaning
`401 Unauthorized`	Missing, invalid, or revoked API key.
`403 Forbidden`	API key is missing the required scope for this endpoint.
`429 Too Many Requests`	Rate limit exceeded for this API key.

Next steps

rocket_launch