Introduction
The ImagineLab API is a REST API over HTTPS. All requests go to https://api.imagineview.art/api/v1, accept and return JSON, and are authenticated with a bearer token. Generation is asynchronous: you create a job, then poll its status until the outputs are ready.
Programmatic access (by request)
Programmatic API access is available on the Ultimate Visionary Studio and Titan Studio plans. Each integration is issued a dedicated, scoped API key — contact our team to request access.Getting Started
- Subscribe to a plan with API access and buy a credit package (every generation spends credits).
- Request an API key for your integration.
- Create a generation with
POST /generations. - Poll
GET /generations/{id}/statusuntil it iscompleted. - Read the result from
GET /generations/{id}.
Authentication
The API authenticates with a secret API key. Include it as a bearer token in the Authorization header on every request:
Authorization: Bearer YOUR_API_KEY
Keep your key secret
Treat your API key like a password. Use it only from your server — never embed it in client-side code, mobile apps, or public repositories. If a key is exposed, revoke it from your dashboard and request a new one.Generations
A generation is an async job. Creating one immediately reserves its credit cost and returns a record with status: "pending". The job then moves through processing to completed or failed.
List available models
Create a generation
Request body:
{
"generation_type": "image", // image | video | music-video | music | voice | text | infographic
"model_name": "seedream-5.0-lite", // from /generations/models
"prompt": "A neon city skyline at dusk, ultra-detailed",
"settings": { "aspect_ratio": "16:9" }, // type-specific, optional
"project_id": null // optional: tag to a project
}curl -X POST https://api.imagineview.art/api/v1/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"generation_type": "image",
"model_name": "seedream-5.0-lite",
"prompt": "A neon city skyline at dusk"
}'{
"id": 1842,
"user_id": 17,
"generation_type": "image",
"model_name": "seedream-5.0-lite",
"prompt": "A neon city skyline at dusk",
"status": "pending",
"credit_cost": 5,
"created_at": "2026-06-07T12:00:00Z",
"outputs": []
}Poll status
{ "id": 1842, "status": "completed", "progress": 100 }Fetch the result
Returns the full generation with an outputs array (media URLs or text). Use GET /generations to list your history (paginated).
End-to-end example
import os, time, requests
BASE = "https://api.imagineview.art/api/v1"
# Load the key from your environment — never hard-code it.
H = {"Authorization": f"Bearer {os.environ['IMAGINELAB_API_KEY']}"}
# 1. Create
gen = requests.post(f"{BASE}/generations", headers=H, json={
"generation_type": "image",
"model_name": "seedream-5.0-lite",
"prompt": "A neon city skyline at dusk",
}).json()
gid = gen["id"]
# 2. Poll
while True:
s = requests.get(f"{BASE}/generations/{gid}/status", headers=H).json()
if s["status"] in ("completed", "failed"):
break
time.sleep(2)
# 3. Result
out = requests.get(f"{BASE}/generations/{gid}", headers=H).json()
print(out["outputs"])Credits & Wallet
Every generation spends credits from your wallet. Creating a job fails with 402 if your balance is too low.
| Generation type | Cost (credits) |
|---|---|
| text | 2 |
| voice | 3 |
| image | 5 |
| music | 8 |
| infographic | 10 |
| video | 15 |
Costs are indicative and may vary by model.
Errors & Limits
The API uses standard HTTP status codes. Error responses contain a detail message.
| Code | Meaning |
|---|---|
| 200 / 201 | Success |
| 400 | Bad request — invalid or missing fields |
| 401 | Missing or invalid bearer token |
| 402 | Insufficient credits |
| 404 | Resource not found |
| 429 | Rate limited — slow down |
| 500 / 502 | Server or upstream model error |
{ "detail": "Insufficient credits" }Need integration help?
For API keys, enterprise, or white-label integrations, reach out to our team.