API Documentation

One endpoint, plain JSON, keys as Bearer tokens. The playground calls exactly what you see here.

basehttps://api.everpod.io

Install

Official SDKs for Python and JavaScript. Or skip them — the API is plain HTTPS + JSON and works with curl alone.

install

pip install everpod

Authentication

Create a key on the API Keys page — it is shown once. Send it as a Bearer token. Keys are stored hashed and can be revoked instantly.

auth

from everpod import Everpod

# reads EVERPOD_API_KEY from the environment
client = Everpod()
# or explicitly:
client = Everpod(api_key="evp_...")

Generate an image

Generation runs as a job on a real GPU node. The SDKs poll to completion for you; over raw HTTP you submit, then poll the job id.

generate

image = client.images.generate(
    prompt="a lighthouse at dusk, cinematic",
    model="z-image-turbo",
)
image.save("lighthouse.png")
print(image.url)

Typical latency on a warm node is a few seconds; the first job after a model loads takes longer.

Jobs: submit, poll, cancel

For queues, pipelines, or UIs that show progress, take the job id and poll yourself. SUCCEEDED, PERMANENT_FAILED, UNCERTAIN and CANCELLED are terminal.

jobs

job = client.images.submit(prompt="a lighthouse at dusk")
job = client.jobs.wait(job.id, timeout=120)   # or client.jobs.retrieve(job.id)
print(job.status, job.artifacts[0].url)

client.jobs.cancel(job.id)  # while it is still queued or running

Models & live capacity

Models are offered only while an online node can actually serve them — ready_workers is live fleet state, not a static catalog. Check before submitting instead of queueing into nothing.

models

for model in client.models.available():
    print(model.name, model.ready_workers)

# raises NoCapacityError if nothing can serve it right now
client.models.require("z-image-turbo")

Usage

Every execution is metered exactly once — totals, per-day, per-model, and the recent execution list. Works with your API key or a console session. Nothing is billed during the pilot.

usage

usage = client.usage.get(days=30)
print(usage.total_jobs, usage.total_gpu_seconds)
for row in usage.recent:
    print(row["job_id"], row["gpu_seconds"], row["created_at"])

Errors

Plain HTTP semantics: 401 bad or revoked key, 404 not yours or missing, 422 invalid request or unknown model, 429 slow down. The SDKs raise typed errors so you can branch without string-matching.

errors

from everpod import JobFailedError, NoCapacityError, UnauthorizedError

try:
    image = client.images.generate(prompt="...", model="wan-2.2-a14b")
except NoCapacityError:
    ...  # nothing can serve this model right now — retry later
except JobFailedError as err:
    print(err.job_id, err.status, err.reason)
except UnauthorizedError:
    ...  # key revoked or wrong