API · v1

ImagineArt 2.0 API Reference

Production-grade text-to-image and image-editing endpoints for engineering teams building consumer apps, internal tooling, and creative pipelines. Synchronous request/response, deterministic seeds, and binary PNG delivery with clean metadata.

Authentication

All requests to /v1 require a long-lived bearer token, provisioned per consumer (mobile app, partner, internal service). Tokens are cryptographically random, opaque, and comparable in constant time. They are revocable in seconds.

Header format

Pass the token in the standard Authorization header.

  • Use HTTPS exclusively. Tokens transmitted over plain HTTP are immediately revoked.
  • Rotate at least every 90 days. Append the new token first, deploy clients, then remove the old.
  • Do not embed tokens in mobile binaries. Proxy through a backend that holds the secret.
curl https://api.ml.imagine.art/v1/models \
  -H "Authorization: Bearer $IMAGINEART_TOKEN"
import os, httpx

client = httpx.Client(
    base_url="https://api.ml.imagine.art/v1",
    headers={"Authorization": f"Bearer {os.environ['IMAGINEART_TOKEN']}"},
    timeout=300.0,
)

r = client.get("/models")
r.raise_for_status()
const token = process.env.IMAGINEART_TOKEN;

const res = await fetch("https://api.ml.imagine.art/v1/models", {
  headers: { "Authorization": `Bearer ${token}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);

Errors

All errors are returned as a JSON envelope with a stable shape. HTTP status carries the broad category; the code string is the machine-readable cause and is safe to switch on.

HTTPCode
400invalid_request, invalid_image
401missing_bearer_token, invalid_token
404unknown_request
429rate_limited
500internal_error
502model_not_available, model_error, model_auth_error
503no_tokens_configured
504timeout
 
{
  "error": {
    "code": "invalid_token",
    "message": "Invalid API token.",
    "request_id": "6a0b3c..."
  }
}

Endpoints

The surface is intentionally small: one endpoint to generate an image from text, one endpoint to edit reference images, plus a discovery endpoint and a health probe. Each request returns a complete result; no polling, queues, or callbacks.

Generate image

Synthesize a new image from a text prompt with ImagineArt 2.0.

POST /v1/images/generations Bearer token required

Request body — multipart/form-data

FieldDescription
prompt required
string		 Text prompt describing the desired image. 1–4000 characters.
aspect_ratiooptional
enum		 Output aspect ratio. 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 4:5, 5:4, 3:1, 1:3, 4:1, 1:4. default: 1:1
resolutionoptional
enum		 Output resolution. 1K (faster) or 2K (higher fidelity).default: 2K
seedoptional
integer		 Deterministic seed. 0, -1, or omitted = random. Reuse a seed for reproducible output.
reasoningoptional
enum		 Visual reasoning level. low (faster) or high (richer compositions).default: low 
curl -X POST https://api.ml.imagine.art/v1/images/generations \
  -H "Authorization: Bearer $IMAGINEART_TOKEN" \
  -F "prompt=A cinematic portrait of a chef plating ramen,
             warm tungsten light, shallow depth of field" \
  -F "aspect_ratio=3:2" \
  -F "resolution=2K" \
  -F "reasoning=high" \
  --output image.png
import httpx

with httpx.Client(timeout=300.0) as client:
    r = client.post(
        "https://api.ml.imagine.art/v1/images/generations",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "prompt": "A cinematic portrait of a chef plating ramen",
            "aspect_ratio": "3:2",
            "resolution": "2K",
            "reasoning": "high",
        },
    )
    r.raise_for_status()
    with open("image.png", "wb") as f:
        f.write(r.content)
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.set("prompt", "A cinematic portrait of a chef plating ramen");
form.set("aspect_ratio", "3:2");
form.set("resolution", "2K");
form.set("reasoning", "high");

const res = await fetch("https://api.ml.imagine.art/v1/images/generations", {
  method: "POST",
  headers: { "Authorization": `Bearer ${token}` },
  body: form,
});
if (!res.ok) throw new Error(await res.text());

await writeFile("image.png", Buffer.from(await res.arrayBuffer()));

Edit image

Edit one or more reference images with ImagineArt 2.0 Edit.

POST /v1/images/edits Bearer token required

Request body — multipart/form-data

FieldDescription
prompt required
string		 Editing instruction. 1–4000 characters.
images required
file[]		 1–4 reference image files. Accepted MIME types: image/png, image/jpeg, image/webp, image/heic, image/heif.
aspect_ratiooptional
enum		 Output aspect ratio. auto matches the first reference image. Also accepts 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9, 4:5, 5:4, 3:1, 1:3. default: auto
resolutionoptional
enum		 1K or 2K.default: 2K
seedoptional
integer		 Deterministic seed. 0, -1, or omitted = random. 
curl -X POST https://api.ml.imagine.art/v1/images/edits \
  -H "Authorization: Bearer $IMAGINEART_TOKEN" \
  -F "prompt=Replace the background with a sunset beach." \
  -F "images=@./portrait.jpg" \
  -F "images=@./reference.png" \
  -F "aspect_ratio=auto" \
  -F "resolution=2K" \
  --output edited.png
import httpx

files = [
    ("images", ("portrait.jpg", open("portrait.jpg", "rb"), "image/jpeg")),
    ("images", ("reference.png", open("reference.png", "rb"), "image/png")),
]
data = {
    "prompt": "Replace the background with a sunset beach.",
    "aspect_ratio": "auto",
    "resolution": "2K",
}

with httpx.Client(timeout=300.0) as client:
    r = client.post(
        "https://api.ml.imagine.art/v1/images/edits",
        headers={"Authorization": f"Bearer {token}"},
        data=data, files=files,
    )
    r.raise_for_status()
    open("edited.png", "wb").write(r.content)
import { readFile, writeFile } from "node:fs/promises";

const form = new FormData();
form.set("prompt", "Replace the background with a sunset beach.");
form.set("aspect_ratio", "auto");
form.set("resolution", "2K");
form.append("images", new Blob([await readFile("portrait.jpg")], { type: "image/jpeg" }), "portrait.jpg");
form.append("images", new Blob([await readFile("reference.png")], { type: "image/png" }), "reference.png");

const res = await fetch("https://api.ml.imagine.art/v1/images/edits", {
  method: "POST",
  headers: { "Authorization": `Bearer ${token}` },
  body: form,
});
await writeFile("edited.png", Buffer.from(await res.arrayBuffer()));

List models

Discover the models available to your tenant and the parameters each accepts.

GET /v1/models Bearer token required

Useful for surfacing model metadata in your own product without hard-coding parameter sets.

curl https://api.ml.imagine.art/v1/models \
  -H "Authorization: Bearer $IMAGINEART_TOKEN"
{
  "data": [
    {
      "id": "text-to-image",
      "name": "ImagineArt 2.0",
      "modality": "text-to-image",
      "parameters": { ... }
    },
    {
      "id": "image-edit",
      "name": "ImagineArt 2.0 Edit",
      "modality": "image-to-image",
      "parameters": { ... }
    }
  ]
}

Service health

Unauthenticated liveness probe for monitors and load balancers.

GET /health Public 
{ "ok": true }