API reference

Read-only mirror of the StudioAxis external API. WorldAxis does not implement these routes.

Base URL: https://studioaxis.io/api/external

For copy-paste workflows: API Examples.

Commercial terms: Pricing. A generation is one successful billed API output (v1 or v2), recorded in usage logs.

Authentication

Rate limits

Response headers (when enabled):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1715789400

Exceeded limits return 429 with Retry-After (seconds).

POST /v1/generate-image

Standard image generation with minimal orchestration. Suitable for simple production paths without the v2 cinematic stack.

URL: https://studioaxis.io/api/external/v1/generate-image

Request body

{
  "prompt": "modern office workspace with natural light",
  "aspectRatio": "16:9",
  "resolution": "2K"
}

Response 200

{
  "success": true,
  "generationId": "gen_123",
  "imageUrl": "https://cdn.studioaxis.io/outputs/gen_123.png",
  "aspectRatio": "16:9",
  "resolution": "2K"
}

Each successful response counts as one generation for usage billing.

Example

curl -X POST "https://studioaxis.io/api/external/v1/generate-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-External-Org-Id: your-org-id" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Product hero on marble surface, soft key light","aspectRatio":"16:9","resolution":"2K"}'

POST /v2/cinematic-image

Cinematic orchestration: semantic translation → creative direction → image generation.

URL: https://studioaxis.io/api/external/v2/cinematic-image

Request body

{
  "prompt": "a team celebrating a product launch in a modern office",
  "category": "category_product_launch",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "cinematicMode": true
}

Visual identity context (brand look, tone, style constraints) is resolved automatically from your organization settings in StudioAxis. It is not a request-time parameter - contact info@studioaxis.io for enterprise brand configuration.

Response 200

{
  "success": true,
  "generationId": "gen_456",
  "imageUrl": "https://cdn.studioaxis.io/outputs/gen_456.png",
  "visualMetaphor": "A dynamic team moment captured with warm cinematic lighting and shallow depth of field",
  "semanticTranslationMs": 842,
  "providerLatencyMs": 3120
}

Example

curl -X POST "https://studioaxis.io/api/external/v2/cinematic-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-External-Org-Id: your-org-id" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Professional consultant presenting strategy in meeting room","category":"category_business_presentation","aspectRatio":"16:9","resolution":"2K"}'

Errors

{
  "success": false,
  "code": "rate_limited",
  "message": "Too many requests per minute",
  "requestId": "req_9m2x1a"
}

Idempotency

Send Idempotency-Key on all POST requests that create billable work.

• Same key + same body → same response (within retention window)
• Same key + different body → 409 idempotency_conflict
• Default retention: 24 hours (enterprise may extend)

Webhooks (enterprise)

Optional completion/failure events to your HTTPS endpoint. Configured in StudioAxis — not via WorldAxis.

Changelog

Contact info@studioaxis.io for sandbox keys.