Generations

Poll until done

Submitting returns immediately; the result arrives when the provider is finished. Read the generation back on an interval until it reaches a terminal state — completed or failed.

Request

curl https://ellisekiz.ai/api/v1/generations/gen_01j... \
  -H "Authorization: Bearer $ELLISEKIZ_TOKEN"

Each call asks the provider for the current state and stores any change, so the endpoint is both the status check and the place where a finished generation gets recorded.

States

Field	Type	Description
`pending`	in flight	The provider is still working, or a transient upstream error was swallowed. Keep polling.
`completed`	terminal	output holds the result URL. Your balance is debited at this moment, once, for the credits quoted at submission.
`failed`	terminal	error explains what the provider said. Nothing is charged.

200 OK · completed

{
  "id": "gen_01j...",
  "status": "completed",
  "provider": "fal",
  "provider_model_id": "fal-ai/flux/schnell",
  "kind": "image",
  "credits": 3000,
  "output": "https://.../image.jpg"
}

A polling loop

Node.js

async function waitFor(id, token) {
  const url = `https://ellisekiz.ai/api/v1/generations/${id}`;
  const headers = { Authorization: `Bearer ${token}` };

  // Images finish in seconds, video in minutes — cap the wait, don't spin.
  for (let attempt = 0; attempt < 200; attempt++) {
    const gen = await fetch(url, { headers }).then((r) => r.json());
    if (gen.status === "completed") return gen.output;
    if (gen.status === "failed") throw new Error(gen.error ?? "generation failed");
    await new Promise((r) => setTimeout(r, 2500));
  }
  throw new Error("timed out waiting for generation");
}

Python

import time, requests

def wait_for(gen_id, token):
    url = f"https://ellisekiz.ai/api/v1/generations/{gen_id}"
    headers = {"Authorization": f"Bearer {token}"}
    for _ in range(200):
        gen = requests.get(url, headers=headers).json()
        if gen["status"] == "completed":
            return gen["output"]
        if gen["status"] == "failed":
            raise RuntimeError(gen.get("error", "generation failed"))
        time.sleep(2.5)
    raise TimeoutError("timed out waiting for generation")

Practical notes

Poll every 2–3 seconds. Faster gains nothing: the provider's own queue sets the pace.
A generation stays readable after it completes; later polls return the stored result without calling the provider again and without charging twice.
Only the account that created a generation can read it — another account's id returns 404, not 403.
Output URLs are provider-hosted and expire. Download anything you intend to keep as soon as the generation completes.
Video jobs can run for several minutes. Poll from a queue or a background worker rather than inside a web request.

Billing happens on the transition to completed, keyed by generation id, so a duplicate poll can never double-charge. Failures are free — see billing.

← PreviousSubmit a generation Next →Routing and BYOK

States

Field	Type	Description
`pending`	in flight	The provider is still working, or a transient upstream error was swallowed. Keep polling.
`completed`	terminal	output holds the result URL. Your balance is debited at this moment, once, for the credits quoted at submission.
`failed`	terminal	error explains what the provider said. Nothing is charged.

200 OK · completed

{
  "id": "gen_01j...",
  "status": "completed",
  "provider": "fal",
  "provider_model_id": "fal-ai/flux/schnell",
  "kind": "image",
  "credits": 3000,
  "output": "https://.../image.jpg"
}

A polling loop

Node.js

async function waitFor(id, token) {
  const url = `https://ellisekiz.ai/api/v1/generations/${id}`;
  const headers = { Authorization: `Bearer ${token}` };

  // Images finish in seconds, video in minutes — cap the wait, don't spin.
  for (let attempt = 0; attempt < 200; attempt++) {
    const gen = await fetch(url, { headers }).then((r) => r.json());
    if (gen.status === "completed") return gen.output;
    if (gen.status === "failed") throw new Error(gen.error ?? "generation failed");
    await new Promise((r) => setTimeout(r, 2500));
  }
  throw new Error("timed out waiting for generation");
}

Python

import time, requests

def wait_for(gen_id, token):
    url = f"https://ellisekiz.ai/api/v1/generations/{gen_id}"
    headers = {"Authorization": f"Bearer {token}"}
    for _ in range(200):
        gen = requests.get(url, headers=headers).json()
        if gen["status"] == "completed":
            return gen["output"]
        if gen["status"] == "failed":
            raise RuntimeError(gen.get("error", "generation failed"))
        time.sleep(2.5)
    raise TimeoutError("timed out waiting for generation")

Practical notes

Poll every 2–3 seconds. Faster gains nothing: the provider's own queue sets the pace.

A generation stays readable after it completes; later polls return the stored result without calling the provider again and without charging twice.

Only the account that created a generation can read it — another account's id returns 404, not 403.

Output URLs are provider-hosted and expire. Download anything you intend to keep as soon as the generation completes.

Video jobs can run for several minutes. Poll from a queue or a background worker rather than inside a web request.

Billing happens on the transition to completed, keyed by generation id, so a duplicate poll can never double-charge. Failures are free — see billing.