API Examples

Practical examples for integrating the Axis API in production workflows.

All requests are executed by StudioAxis:

WorldAxis is a documentation layer only. Nothing on this page is hosted or implemented here.

1. Basic image generation (v1)

Simple text-to-image generation without the v2 orchestration stack. Use when you need a direct generation pass with minimal semantic layering.

Request

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 "Content-Type: application/json" \
  -d '{
    "prompt": "modern office workspace with natural light",
    "aspectRatio": "16:9",
    "resolution": "2K"
  }'

Response

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

2. Cinematic generation (v2)

Axis v2 applies cinematic orchestration on top of the image engine:

• Semantic visual translation
• Category-based scene structure
• Creative direction parameters

This is not a single prompt forwarded to a model. The request is interpreted, structured, and then rendered.

Request

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 "Content-Type: application/json" \
  -d '{
    "prompt": "a team celebrating a product launch in a modern office",
    "category": "category_product_launch",
    "aspectRatio": "16:9",
    "resolution": "2K",
    "cinematicMode": true
  }'

Response

{
  "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
}

semanticTranslationMs is orchestration time before generation. providerLatencyMs is the underlying image provider. Together they explain where latency comes from — useful for enterprise SLAs and debugging.

3. Brand-aware generation (cinematic + identity)

Combines v2 orchestration with brand context. Axis constrains composition, lighting, and tone to match your organization's declared visual identity.

Brand context is configured in StudioAxis and applied per organization. It is not passed as a raw string at request time - it is resolved from your organization settings.

Request

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 "Content-Type: application/json" \
  -d '{
    "prompt": "professional consultant presenting strategy in meeting room",
    "category": "category_business_presentation",
    "aspectRatio": "16:9",
    "resolution": "2K"
  }'

Brand identity constraints are automatically applied based on your organization settings in StudioAxis. No additional parameters required at request time - Axis resolves visual identity from your configured organization context.

What Axis adds

4. Visual intent system (advanced orchestration)

This is the primary difference versus standard image APIs.

You send a brief and category. Axis resolves directed intent before pixels are generated.

Example input

{
  "prompt": "real estate agent showing apartment to client",
  "category": "category_customer_story"
}

Axis resolves internally

Visual identity constraints from your organization settings are layered on top of this resolved intent automatically.

Result

A directed cinematic frame — not a generic completion from a raw prompt.

5. Error handling

Errors use a consistent envelope. Always inspect code for programmatic handling.

Rate limit exceeded

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

HTTP 429. Honor Retry-After when present.

Invalid API key

{
  "success": false,
  "code": "unauthorized",
  "message": "Invalid API key"
}

HTTP 401.

Invalid request

{
  "success": false,
  "code": "bad_request",
  "message": "Invalid category or missing required fields"
}

HTTP 400.

See API reference for the full error matrix and idempotency behavior.

6. Axis vs traditional image APIs

Traditional AI image APIs

One hop. No semantic layer, no brand enforcement, no structured creative metadata in the response.

Axis

prompt + category + visual identity context
  → semantic interpretation
  → creative direction / visual intent
  → image generation engine (e.g. Gemini / Vertex class)
  → structured output + public asset URL + usage log

Multiple hops, each observable. Generation is the last step, not the only step.

7. When to use which API

8. Next steps

For sandbox keys and enterprise setup: info@studioaxis.io.