Where to start with the queue API

The path to a first generation on the queue API: issue a key, pick a model by its identifier, submit the job, poll its status, download the output.

This page is not the contract; it is the order you read it in. The full contract — every endpoint, status value and error code — lives in the API documentation, and each step below links into it.

The path to a first generation

Each step ends in the part of the documentation that owns it: a summary here, the contract there.

  1. Issue an API key

    Keys are created in the panel and travel in the Authorization header. Everything under /v1 is behind that gate; the single exception is the public catalog endpoint, which needs no key.

    Authentication

  2. Pick a model by its identifier

    A model is called by its namespaced identifier. The identifier is stable even when the version behind it is replaced, so it is the one string your code should hold on to.

    Catalog

  3. Hand the job to the queue

    Generation takes minutes, not seconds, so submitting returns an identifier rather than an output. Short jobs have a single-call path, but anything long belongs in the queue.

    First request

  4. Poll the status, handle the codes

    Status is read from a separate endpoint and each state is named. Rate limits are counted in the database, not in process memory, so a limit reached on one request is still there on the next.

    Statuses and errors

  5. Collect the output within seven days

    Bytes come down from our own domain, never from a provider URL. After seven days the output is deleted together with the input that produced it: download what you want to keep.

    Retention window

The catalog your code can call

These numbers are not typed in by hand: they are derived from the public endpoint that lists the models, and they change the day the catalog does.

  • 275 Callable models — Every row in the catalog is called by its namespaced id, and the list is public.
  • 19 Model makers — The company that built the model is named in the catalog, and you can filter by it.
  • 3 Media types — Image, Video, and Audio — the three share one request shape and one billing path.

The rules that bind an integration

All four are written decisions, and the documentation says the same; the current limit values live there, not here.

Authentication is not optional
An unguessable URL is not authentication. Every /v1 endpoint checks the key; the one public endpoint is the model catalog, and the signed upload path a provider fetches from is deliberately outside /v1 with a signature and an expiry instead of a session.
Rate limits survive the isolate
The counter lives in the database, so it does not reset when a new isolate starts. Treat the limit response as a real one: back off and retry later rather than looping.
Failures close, they do not guess
Every error carries a code, and the fail-closed side is refusing. A charge that cannot be computed shows a dash rather than a zero, because zero reads as free.
Charges are integers, prompts are not archived
Amounts are pico-USD integers — trillionths of a dollar — and money arithmetic never touches floating point. The input of a generation lives only beside its output and is deleted with it; there is no separate prompt log.