# Arles

> Make pictures from a prompt, and fetch them when they are ready. You describe a picture, Arles makes it, you say what is wrong with it in ordinary words, and a language model rewrites the description so you can send it again.

## The API

- [The Arles API](https://arles.hu/api): what the API does and how to use it, in prose.
- [OpenAPI](https://arles.hu/api/v1/openapi): the same thing as an OpenAPI 3.1 document.

## What to know first

- 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.

## Endpoints

- `GET /api/v1/me` — The account behind the token, its role, and what a round of yours may ask for.
- `GET /api/v1/sessions` — Every session of yours, most recently used first.
- `POST /api/v1/sessions` — Make a session with a name of your choosing.
- `GET /api/v1/sessions/{session}/rounds` — Every round in one session of yours, most recent first, a page at a time.
- `POST /api/v1/rounds` — Ask for a round. The prompt is the only thing you must send.
- `GET /api/v1/rounds/{round}` — The state of one round and the pictures it has made so far.
- `GET /api/v1/images/{image}` — The PNG itself.