Developer Documentation

import os, time, requests

BASE = "https://api.imaginelab.art/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['IMAGINELAB_API_KEY']}",
    "Content-Type": "application/json",
}

# 1. Create a generation job
res = requests.post(f"{BASE}/generations", headers=HEADERS, json={
    "generation_type": "image",
    "model_name": "seedream-5-lite",
    "prompt": "A neon city skyline at dusk, ultra-detailed, cinematic lighting",
    "settings": {"aspect_ratio": "16:9"},
})
res.raise_for_status()
job = res.json()
job_id = job["id"]
print(f"Job created: {job_id}  (status: {job['status']})")

# 2. Poll until complete
MAX_POLLS = 60          # 60 × 3 s = 3-minute timeout
for attempt in range(MAX_POLLS):
    time.sleep(3)
    status_res = requests.get(f"{BASE}/generations/{job_id}/status", headers=HEADERS)
    status_res.raise_for_status()
    status = status_res.json()
    print(f"  [{attempt+1}/{MAX_POLLS}] status={status['status']}  progress={status.get('progress', 0)}%")
    if status["status"] == "completed":
        break
    if status["status"] == "failed":
        raise RuntimeError(f"Generation failed: {status.get('error_message', 'unknown')}")
else:
    raise TimeoutError("Generation did not complete within the polling window.")

# 3. Fetch result
result = requests.get(f"{BASE}/generations/{job_id}", headers=HEADERS).json()
for output in result["outputs"]:
    print("Output URL:", output["url"])

import axios from 'axios';

const BASE = 'https://api.imaginelab.art/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.IMAGINELAB_API_KEY}`,
  'Content-Type': 'application/json',
};

async function generateImage(prompt: string): Promise<string[]> {
  // 1. Create
  const { data: job } = await axios.post(`${BASE}/generations`, {
    generation_type: 'image',
    model_name: 'seedream-5-lite',
    prompt,
    settings: { aspect_ratio: '1:1' },
  }, { headers });

  // 2. Poll with exponential back-off
  const startedAt = Date.now();
  const TIMEOUT_MS = 3 * 60 * 1000;   // 3 minutes
  let delay = 2000;

  while (Date.now() - startedAt < TIMEOUT_MS) {
    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 8000); // cap at 8 s

    const { data: s } = await axios.get(`${BASE}/generations/${job.id}/status`, { headers });
    if (s.status === 'completed') break;
    if (s.status === 'failed') throw new Error(`Generation failed: ${s.error_message}`);
  }

  // 3. Result
  const { data: result } = await axios.get(`${BASE}/generations/${job.id}`, { headers });
  return result.outputs.map((o: { url: string }) => o.url);
}

generateImage('A serene forest at golden hour').then(console.log);

Authorization: Bearer YOUR_API_KEY

{ "status": "ok", "version": "v1", "timestamp": "2026-08-23T09:00:00Z" }

{
  "models": [
    {
      "name": "seedream-5-lite",
      "generation_type": "image",
      "provider": "ByteDance",
      "available": true
    },
    ...
  ]
}

{
  "generation_type": "image",
  "model_name": "seedream-5-lite",
  "prompt": "A neon city skyline at dusk, ultra-detailed, cinematic lighting",
  "settings": {
    "aspect_ratio": "16:9",
    "quality": "high"
  }
}

curl -X POST https://api.imaginelab.art/api/v1/generations \
  -H "Authorization: Bearer $IMAGINELAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "image",
    "model_name": "seedream-5-lite",
    "prompt": "A neon city skyline at dusk",
    "settings": { "aspect_ratio": "16:9" }
  }'

{
  "id": "gen_8f3a21c7",
  "generation_type": "image",
  "model_name": "seedream-5-lite",
  "prompt": "A neon city skyline at dusk, ultra-detailed, cinematic lighting",
  "status": "pending",
  "credit_cost": 5,
  "settings": { "aspect_ratio": "16:9", "quality": "high" },
  "created_at": "2026-08-23T09:01:00Z",
  "outputs": []
}

{
  "id": "gen_8f3a21c7",
  "status": "processing",
  "progress": 62,
  "estimated_remaining_seconds": 14
}

{
  "id": "gen_8f3a21c7",
  "status": "completed",
  "progress": 100,
  "estimated_remaining_seconds": 0
}

{
  "id": "gen_8f3a21c7",
  "generation_type": "image",
  "status": "completed",
  "credit_cost": 5,
  "outputs": [
    {
      "url": "https://cdn.imaginelab.art/outputs/gen_8f3a21c7/result.png",
      "mime_type": "image/png",
      "width": 1920,
      "height": 1080,
      "expires_at": "2026-09-22T09:01:00Z"
    }
  ],
  "created_at": "2026-08-23T09:01:00Z",
  "completed_at": "2026-08-23T09:01:24Z"
}

{
  "generations": [ { "id": "gen_8f3a21c7", "status": "completed", ... }, ... ],
  "cursor": "eyJpZCI6MTgzMH0=",
  "has_more": true
}

{
  "balance": 1240,
  "plan": "Ultimate Visionary Studio",
  "plan_edt_reset_at": "2026-09-01T00:00:00Z",
  "topup_balance": 500,
  "currency": "EDT"
}

{
  "code": "INSUFFICIENT_CREDITS",
  "detail": "Your wallet balance (3 EDT) is below the required cost (5 EDT).",
  "request_id": "req_f7c3a9b1"
}

{
  "id": "gen_9b2c11f4",
  "status": "failed",
  "error_message": "The upstream model returned an empty result. The prompt may contain content that cannot be processed.",
  "credit_cost": 0,
  "outputs": []
}

import time, math, requests

def poll_until_done(base_url, job_id, headers, timeout=300):
    """Poll status with exponential back-off. Raises on timeout or failure."""
    deadline = time.monotonic() + timeout
    delay = 2.0
    attempt = 0
    while time.monotonic() < deadline:
        r = requests.get(f"{base_url}/generations/{job_id}/status", headers=headers)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", delay))
            time.sleep(wait)
            continue
        r.raise_for_status()
        data = r.json()
        if data["status"] == "completed":
            return data
        if data["status"] == "failed":
            raise RuntimeError(data.get("error_message", "Generation failed"))
        delay = min(delay * 1.5, 10.0)  # cap at 10 s
        attempt += 1
        time.sleep(delay)
    raise TimeoutError(f"Job {job_id} did not complete within {timeout}s")