AkurAI-Framework / site/content/docs/images.md

Latest change 40e7ccf643510ab1faf1693f1491727fbfac8767 - File copies for any stored file (AKURAI_FILE_COPY_DIR/COLLECTIONS) replace the image API's save dir by Ólafur Búi Ólafsson

# Image generation API

`POST /api/images/generations` generates an image through an upstream image API
and stores it in a collection's `file` field — no handler code. Point it at any
plain-HTTP image endpoint (an OpenAI-compatible `/v1/images/generations`, or a
richer native one such as Unsloth Studio's `/api/inference/images/generate`).

## Configuration

| Variable | Meaning | Default |
| -------- | ------- | ------- |
| `AKURAI_IMAGE_URL` | Full URL the parameters are POSTed to | _unset_ → `503` |
| `AKURAI_IMAGE_API_KEY` | Bearer token for the upstream | _unset_ |
| `AKURAI_IMAGE_TIMEOUT` | Upstream timeout in seconds | `900` |

Plain HTTP only, like the [assistant](/docs/assistant-api) and embedding
clients: terminate TLS at the edge.

To also keep every stored image on disk, use the collections-wide
[file copies](/docs/auto-api#file-copies) (`AKURAI_FILE_COPY_DIR`).

## Request

```json
{
  "collection": "images",
  "field": "image",
  "record": { "parent": 3 },
  "params": { "prompt": "a fox", "steps": 40, "init_image": "blob:9f8e…c0" }
}
```

- `collection` / `field` — where the image is stored; `field` must be a `file`
  field.
- `params` — sent to the upstream as the JSON body, untouched except that a
  string `"blob:<id>"` (top level or inside an array) becomes a `data:` URL of
  that stored blob. Image edits therefore reference stored images by blob id
  instead of uploading them from the browser.
- `record` — extra fields for the new record (e.g. a `parent` relation).

## Response

`201` with the created record. Its fields come from `record`, then every
**declared** field found in `params`, then every declared field on the upstream's
image item (so a `seed` field stores the seed the upstream actually used), plus
the file descriptor. If the collection declares an `int` field named
`duration_ms`, it records the upstream round-trip time in milliseconds. Unknown
keys are ignored; an integer sent for a `float`
field is stored as a float.

The upstream may answer with `data[]` (OpenAI) or `images[]`; the first item's
`b64_json` is decoded, or its `url` is fetched from the upstream origin with the
same bearer.

| Status | When |
| ------ | ---- |
| `201` | Image generated and stored |
| `400` | Body is not JSON, or lacks `collection`, `field` or an object `params` |
| `404` | Unknown collection |
| `502` | Upstream unreachable, non-2xx (its message is included), or no image |
| `503` | `AKURAI_IMAGE_URL` unset or not plain HTTP |