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. The share endpoints under `/api/v1/public` are the exception: a share link is public, so they take no token and are counted by address.
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. A share endpoint serves what the link serves and nothing more, and no endpoint ever says who voted for a picture, only how many did.
Two hundred requests every thirty seconds 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 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.
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.
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.
-
namestring optional - What to call it. Left out, it is named for you.
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.
sessioninteger- The session id, from your sessions.
per_pageinteger- How many rounds one page holds, between 1 and 100. Left out, twenty five.
The pictures in one session of yours that got votes on its shared page, most votes first.
Pictures nobody voted for are left out. Each picture carries `votes` and `round`: the id, number and prompt of the round that made it, and where to ask for the whole round. Only counts are given, never who voted. Votes belong to the picture, so they are here whether or not the session is still shared.
sessioninteger- The session id, from your sessions.
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.
-
promptstring required - What you want a picture of, in prose. 100 to 200 words reads best.
-
qualitystring 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.
-
imagesinteger optional - How many pictures this round makes. Left out, the default is used. Clamped to what your role allows.
-
sizestring optional - The shape of the picture, width x height: 1024x1024, 1328x768, 768x1328, 864x1344, 1328x1328. 864x1344 is 9:14, the shape of a playing card. Left out, 1024x1024 is used. Any other value is refused with 422.
-
sessioninteger optional - The session to put it in. Left out, one is made.
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.
roundinteger- The id you were given.
Stop a round that is still waiting in the queue.
Only a queued round can be cancelled: once the image service has started on it, it cannot be interrupted. A running or finished round is refused with 409, and the refusal carries its `status`. Cancelling a round that is already cancelled answers as if it had just been. A cancelled round can then be deleted.
roundinteger- The id you were given.
The round and every picture it made, files included.
Refused with 409 while the round is queued or running, and when other rounds were continued from it. The refusal carries `children`, the ids of those rounds: delete them first. Deleting cannot be undone.
roundinteger- The id you were given.
The folder or session behind a share link: which of the two it is, its name, and how many pictures it holds.
No token. A share link is public, so these four endpoints are too, and they are counted by address rather than by token. They give what the link gives and nothing more: a uuid that names nothing, or something no longer shared, answers 404, and holding a token for the account that shared it changes none of that.
sharestring- The uuid from the share link, the same one /shared/{uuid} opens.
The pictures behind a share link, a page at a time, in either of the two orders the shared page offers.
No token. Each picture carries its size, its vote count and where to fetch its bytes, and those links are the share's own: they need no token either. `sort=order` is the order the folder or session itself has. `sort=votes` is the upvoted ones, most votes first, and pictures nobody voted for are left out, exactly as the shared page reads it. Only counts are given, never who voted.
sharestring- The uuid from the share link.
sortstring- `order` or `votes`. Left out, `order`.
per_pageinteger- How many pictures one page holds, between 1 and 100. Left out, 60.
The PNG itself, for a picture the link holds.
No token. The bytes, not a link to them. Add /thumbnail for a small one. A picture that is not in what this link shared answers 404, whoever is asking.
sharestring- The uuid from the share link.
imageinteger- The id from the list of pictures.
The PNG itself.
The bytes, not a link to them. Add /thumbnail for a small one.
imageinteger- The id from a round.