API Documentation

One REST endpoint for AI image generation. Choose your model per request and get back a hosted image URL — in any language, from any backend.

✓ Free API✓ REST API✓ JSON Responses✓ HTTPS✓ AI Image Generation✓ API Key Authentication

Getting started

Introduction#

Imagination AI routes your prompt to the image model you pick and returns a hosted image URL. Every model shares one request shape, so switching from photoreal to anime is a one-field change. Responses are JSON, transport is HTTPS, and authentication is a single API key issued instantly by our Telegram bot.

Getting started

Quick Start#

1️⃣

Get an API key

Open the Telegram bot and tap 🔑 Create API key.

2️⃣

Send your first request

POST a prompt to /api/public/v1/images with your key.

3️⃣

Receive an image URL

The JSON response returns a hosted image_url.

4️⃣

Display or download

Render the URL in your app or save the bytes server-side.

A complete working example:

cURL

curl -X POST https://visionary-vision-api.lovable.app/api/public/v1/images \
  -H "Authorization: Bearer IMG-RAGE-XXXX-XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a neon cyberpunk fox in the rain","model":"flux","width":1024,"height":1024}'

Getting started

Authentication#

Send your key as a bearer token. The x-api-key header and an ?apikey= query parameter are also accepted.

Header

Authorization: Bearer IMG-RAGE-XXXX-XXXXXX

Alternative

x-api-key: IMG-RAGE-XXXX-XXXXXX

🔒 Security note

Never expose your API key in frontend applications. Always use a backend server or serverless function to protect your API key.

Getting started

Base URL#

All endpoints are served over HTTPS from a single, stable API base URL. This base URL is independent of the documentation website — if these docs ever move to a different domain, your integration keeps working unchanged and your API keys stay valid.

Base URL

https://visionary-vision-api.lovable.app/api/public/v1

🔄 Always in sync

Our model catalogue updates itself automatically. Call GET /api/public/v1/models when you connect a key, refresh models, or start a session and you will always have the current list — new models appear, changed metadata refreshes, and retired models are marked unavailable. No code changes on your side, ever.

API reference

Generate Images#

POST/api/public/v1/images

Generate an image from a text prompt with the model of your choice. Returns a hosted image URL.

Authentication: Required — bearer token or x-api-key header.

Headers

Authorization: Bearer IMG-RAGE-XXXX-XXXXXX
Content-Type: application/json

Request body

JSON

{
  "prompt": "a neon cyberpunk fox in the rain",
  "model": "dall-e-3-xl",
  "width": 1024,
  "height": 1024
}

Example request

cURL

curl -X POST https://visionary-vision-api.lovable.app/api/public/v1/images \
  -H "Authorization: Bearer IMG-RAGE-XXXX-XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a neon cyberpunk fox in the rain","model":"flux","width":1024,"height":1024}'

Successful response — 200

200 OK

{
  "success": true,
  "model": "DALL-E 3 XL",
  "prompt": "a neon cyberpunk fox in the rain",
  "width": 1024,
  "height": 1024,
  "image_url": "https://cdn.example.com/generated/abc123.png",
  "latency_ms": 4213
}

Error responses

400 validation

HTTP/1.1 400 Bad Request

{
  "success": false,
  "error": {
    "code": "invalid_prompt",
    "message": "A 'prompt' between 1 and 2000 characters is required."
  }
}

401 unauthorized

HTTP/1.1 401 Unauthorized

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "This API key is invalid, revoked or suspended. Generate a new one from the Telegram bot."
  }
}

429 rate limited

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 20 requests per minute for this API key. Wait a moment and retry.",
    "limit_per_minute": 20,
    "retry_after_seconds": 60
  }
}

500 server error

HTTP/1.1 500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "internal_server_error",
    "message": "Something went wrong while generating the image. Please retry."
  }
}

Supported parameters

prompt, model, width, height — see the full table below.

API reference

Parameter reference#

These are every parameter the images endpoint accepts today. Anything else in the body is ignored.

Parameter	Type	Required	Description
prompt	string	Required	What to generate. 1–2000 characters.
model	string	Optional	Model slug from GET /api/public/v1/models. Defaults to "flux".
width	integer	Optional	Image width in pixels, clamped to 256–2048. Defaults to 1024.
height	integer	Optional	Image height in pixels, clamped to 256–2048. Defaults to 1024.

Parameters such as seed, negative_prompt, steps and guidance are not exposed by this API yet and are ignored if sent.

API reference

Get Models#

GET/api/public/v1/models

List every model that is currently enabled, with its slug, display name and description.

Authentication: Optional — a valid key is validated if sent, otherwise the list is public.

API reference

Health Check#

GET/api/public/v1/health

Lightweight liveness probe for monitoring and deploy checks.

Authentication: None — this endpoint is public.

API reference

Fallback Behaviour#

If the requested model is temporarily unavailable, Imagination AI may automatically use a compatible fallback model so your request still succeeds. The response always reports which model produced the image in the model field — read it if the exact model matters to your product.

Examples

Code Examples#

The same request in six languages. Switch tabs to change the language — everything else stays identical.

cURL

curl -X POST https://visionary-vision-api.lovable.app/api/public/v1/images \
  -H "Authorization: Bearer IMG-RAGE-XXXX-XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a neon cyberpunk fox in the rain","model":"flux","width":1024,"height":1024}'

Examples

Playground#

Pick a model, tweak the prompt and send a real request with your own key.

No models available yet.

Paste an API key from the bot to send a real request.

curl -X POST https://visionary-vision-api.lovable.app/api/public/v1/images \
  -H "Authorization: Bearer IMG-RAGE-XXXX-XXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a neon cyberpunk fox in the rain","model":"flux","width":1024,"height":1024}'

Examples

Image Gallery#

Example outputs and the prompts behind them.

“a neon cyberpunk fox in the rain, volumetric lighting”
`model: "cyberpunk"`

“futuristic green city skyline at sunrise, ultra detailed”
`model: "dall-e-3-xl"`

“a serene mountain lake at dawn, mist over the water”
`model: "realistic"`

“friendly studio-lit robot holding a paintbrush”
`model: "flux"`

Examples

Model Catalogue#

Live list — everything below can be called today. Fetch it programmatically with GET /api/public/v1/models.

Resources

Rate Limits#

Each API key gets a fixed budget per rolling minute (20 by default). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; exceeding the budget returns 429 with a Retry-After header.

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 20 requests per minute for this API key. Wait a moment and retry.",
    "limit_per_minute": 20,
    "retry_after_seconds": 60
  }
}

Resources

Error Codes#

Every failure returns the same shape: { success: false, error: { code, message } }.

Status	Code	Description
400	invalid_json	The request body is not valid JSON.
400	invalid_prompt	Prompt is missing, empty or longer than 2000 characters.
400	unknown_model	The model slug does not exist or is currently disabled.
401	missing_api_key	No key was sent in the Authorization or x-api-key header.
401	invalid_api_key	The key is invalid, revoked or suspended.
404	not_found	The requested path does not exist on this API.
429	rate_limit_exceeded	Too many requests for this key in the current minute.
500	internal_server_error	Unexpected failure on our side. Retry with backoff.

Resources

FAQ#

Is the API really free?

Yes. Imagination AI is free to use — there is no billing, no plan and no card required. Keys are limited only by a per-minute rate limit.

Do API keys expire?

No. A key stays valid until you revoke it from the Telegram bot or an administrator suspends it.

Can I call the API from the browser?

Technically yes (CORS is open), but you should not — that exposes your key. Proxy the call through your own backend or a serverless function.

How do I change models?

Send a different model slug in the model field. The full live list is available from GET /api/public/v1/models.

What happens if a model is unavailable?

We reroute to a compatible fallback model so your request still returns an image. The model field in the response tells you what actually generated it.

How do I rotate a leaked key?

Use 🔄 Revoke & regenerate key in the Telegram bot. The old key stops working immediately.

Ready to build?

Grab a free key from the Telegram bot and send your first request in under a minute.