Developers

Text-to-Image API

An async, task-based REST API: submit a prompt, get a `task_id` immediately (HTTP 202), then poll until the image URL is ready. One key works across capabilities; failed tasks never consume quota.

Last updated: 2026-11-08

Quick start

Issue a key on your account page, then submit a task with X-API-Key:

# 1. Submit — returns HTTP 202 with a task_id immediately
curl -X POST https://create.litelake.com/api/open/t2i \
  -H "X-API-Key: lcr_…" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a calm lake at dawn, soft light","aspect_ratio":"16:9","output_format":"png"}'

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "tsk_…",
    "status": "queued",
    "capability": "t2i",
    "created_at": "2026-11-08T02:00:00Z",
    "usage": {
      "personal": { "used_today": 1, "limit_per_day": 1 },
      "site_free": { "used_today": 3, "limit_per_day": 10 },
      "reset_at_utc": "…"
    }
  }
}

# 2. Poll — every 2 seconds until status is a terminal state
curl https://create.litelake.com/api/open/tasks/tsk_… \
  -H "X-API-Key: lcr_…"

{
  "code": 200,
  "message": "ok",
  "data": {
    "task_id": "tsk_…",
    "status": "succeeded",
    "capability": "t2i",
    "prompt": "a calm lake at dawn, soft light",
    "aspect_ratio": "16:9",
    "output_format": "png",
    "image": { "url": "https://…", "expires_at": "…" },
    "error": null,
    "latency_ms": 8210,
    "created_at": "2026-11-08T02:00:00Z",
    "finished_at": "2026-11-08T02:00:09Z"
  }
}

Authentication

All open endpoints authenticate with a request header: X-API-Key: lcr_…. Create keys on your account page; the full key is shown only once at issuance. Keys inherit your personal daily quota; super keys (issued through the Admin Center) are unlimited.

Submit — POST /api/open/t2i

Returns HTTP 202 (acceptance) with the envelope above. The task is queued; nothing is returned synchronously.

Parameter	Type	Description
`prompt`	`string`	Required. What to generate, up to 2000 characters.
`aspect_ratio`	`"1:1"` \| `"2:3"` \| `"3:2"` \| `"3:4"` \| `"4:3"` \| `"9:16"` \| `"16:9"`	Defaults to `1:1`.
`output_format`	`"png"` \| `"jpeg"` \| `"webp"`	Defaults to `png`.

Poll — GET /api/open/tasks/{task_id}

Returns the task resource. status walks the pipeline:

Status	Meaning
`queued`	Accepted, waiting for a worker.
`submitted`	Sent to the upstream model.
`running`	The model is generating.
`transferring`	Generated — the image is being copied to storage.
`succeeded`	Done. `image.url` is the download link (keep for 24h per fetch; image itself retained 7 days).
`failed`	`error.code` / `error.message` say why. Quota was not consumed for upstream failures.
`expired`	The result window lapsed before retrieval. Submit again.

Poll every 2 seconds. Tasks typically finish in about 10 seconds; stop polling after 90 seconds and treat the task as still-running (check again later).

List tasks — GET /api/open/tasks?limit=N

Returns your most recent tasks, newest first (limit defaults to 20).

Error codes

Business errors keep the envelope with a code in body.code. Codes below apply to both the open API and the signed-in playground.

Code	Meaning
`40001`	invalid_params — a parameter is missing or outside the whitelist.
`40021`	prompt_too_long — prompt exceeds 2000 characters.
`40102`	unauthorized — no valid session or key (HTTP 401 on the user surface).
`40301`	account_suspended — the account is banned.
`42901`	personal daily quota exhausted — resets at 00:00 UTC.
`42902`	site-wide free budget exhausted — resumes at the next UTC day.
`42903`	concurrency limit — wait for your in-flight task to finish, then submit again.
`50021`	upstream generation failed — retry later; quota not consumed.
`50022`	upstream timeout — retry; quota not consumed.
`50023`	network error interrupted the task — retry.
`50024`	rate-limit store unavailable — retry shortly.
`50025`	upstream busy — retry shortly; quota not consumed.

Limits & notes

Free Beta: 1 successful generation per user per day (UTC reset); failed or timed-out tasks do not count.
The free tier also shares a site-wide daily budget; when it runs out (42902), generation resumes at the next UTC day.
Generated images are retained for 7 days. The image.url returned per poll is a direct link valid for 24 hours after each fetch — re-fetch the task to get a fresh link.
Concurrency: one in-flight task per identity (42903).
Capability is fixed to t2i in Beta; more dimensions (image-to-image, text-to-video) are planned.