Arles Back to the front page
The Arles API

The Arles API

Make pictures from a prompt, and fetch them when they are ready.

Every request carries a token: `Authorization: Bearer <token>`. You make yours on your settings screen in Arles, it is shown once, and making a second one replaces the first.

Asking for a round answers straight away with the round, not with a picture. Ask about the round again until it says done, then fetch its images. About once a second is right.

You reach your own work and nothing else. Somebody else's round or picture answers 404, never 403.

Sixty requests a minute per token. Every answer carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, so a loop can pace itself without counting, and a 429 carries `Retry-After`. Your role sets the best quality and the largest number of images one round may ask for, and the service clamps whatever you send to it rather than refusing.

Errors are JSON with a `message`. 401 means the token is missing or no longer good, 404 means it is not there or not yours, 422 means the request was wrong, 429 means too many requests.

The OpenAPI document The short version, for a model
What you can ask for
GET /api/v1/me Who the token belongs to

The account behind the token, its role, and what a round of yours may ask for.

Ask this first. It tells you the ceilings the service will clamp your round to, so you do not have to guess them.

What comes back: The account, its role, the best quality and the largest number of images one round may ask for, every quality name there is, and what has been spent so far.
GET /api/v1/sessions Your sessions

Every session of yours, most recently used first.

A session is one piece of work and holds the rounds that belong to it. Use this to find the id to send with a round, so related work stays together.

What comes back: A list of sessions with an id, a name, how many rounds each holds and when it was last used.
POST /api/v1/sessions Start a session

Make a session with a name of your choosing.

Optional. A round sent with no session makes one, and a language model names it from the first prompt.

What you send
name string optional
What to call it. Left out, it is named for you.
What comes back: The session.
GET /api/v1/sessions/{session}/rounds The rounds in a session

Every round in one session of yours, most recent first, a page at a time.

This is how you find work you made earlier without having kept the ids. A page holds twenty five rounds unless you ask for another number, and the answer carries the usual links and meta so you can walk through the rest.

In the address
session integer
The session id, from your sessions.
per_page integer
How many rounds one page holds, between 1 and 100. Left out, twenty five.
What comes back: A page of rounds, each shaped as one round is, with the images it has made.
POST /api/v1/rounds Make images

Ask for a round. The prompt is the only thing you must send.

A round is queued and answered at once with its id: making an image takes about ten seconds and the image service does one at a time, so nothing here waits for a picture. Ask for the round again to see how it is getting on.

What you send
prompt string required
What you want a picture of, in prose. 100 to 200 words reads best.
quality string optional
How much work goes into each image: Draft, Normal, Fine or Best. Left out, Normal is used. Clamped to what your role allows. A step count is not accepted: what one is worth belongs to the checkpoint the image service has loaded, and that changes.
images integer optional
How many pictures this round makes. Left out, the default is used. Clamped to what your role allows.
size string optional
The shape of the picture. Left out, the default is used.
session integer optional
The session to put it in. Left out, one is made.
What comes back: 202 with the round, its session, and where to ask about it.
GET /api/v1/rounds/{round} How a round is getting on

The state of one round and the pictures it has made so far.

Queued, running, done, failed or cancelled. The images arrive one at a time, so this can answer with some of them while the round is still running. While a round is unfinished it also carries `queue_position`, how many rounds are in front of it, and `estimated_wait_seconds`, roughly how long until it has made its last image. Both are null once it is finished. Poll on the wait rather than every second: the estimate is arithmetic at about ten seconds an image and does not know that a service which has been idle spends about two minutes forty loading its weights first.

In the address
round integer
The id you were given.
What comes back: The round, its state, where it stands in the queue, what it has cost, and every image it has made with a link to each.
GET /api/v1/images/{image} One picture

The PNG itself.

The bytes, not a link to them. Add /thumbnail for a small one.

In the address
image integer
The id from a round.
What comes back: image/png.