# API for programs / API สำหรับโปรแกรมอื่น

Base URL: `https://api.wxch.org/v1` (your own domain: the `api.` name). Every call needs an API key
(`Authorization: Bearer <key>`; create keys on the control page, tab API). Errors have the OpenAI shape:
`{"error":{"message":"...","type":"...","code":"..."}}`.

## Chat (since the start)
`GET /v1/models`, `POST /v1/chat/completions`, `/v1/completions`, `/v1/embeddings`: OpenAI-compatible.

## Images, speech: the OpenAI shapes (they wait for the result)

These need a machine that has the AI module installed (see INSTALL.md). If none is online you get `503 service_unavailable`.
A call can take from seconds to a few minutes; keep the connection open (hanging up cancels the job).

```sh
# text to image (image.generate). n = 1..4, size must be one the module offers (1024x1024, 1344x768, 768x1344, 512x512)
curl https://api.wxch.org/v1/images/generations -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"a lighthouse at dawn","n":1,"size":"1024x1024"}'          # -> {"data":[{"url":"https://..."}]}
#   "response_format":"b64_json" returns the picture inside the answer instead of a link (the link is valid for an hour)

# edit a picture (image.edit)
curl https://api.wxch.org/v1/images/edits -H "Authorization: Bearer $KEY" -F image=@photo.png -F prompt="make the sky pink"

# speech to text (audio.transcribe). response_format: json (default) | text | srt | vtt | verbose_json
curl https://api.wxch.org/v1/audio/transcriptions -H "Authorization: Bearer $KEY" -F file=@talk.mp3 -F language=th -F response_format=srt
curl https://api.wxch.org/v1/audio/translations   -H "Authorization: Bearer $KEY" -F file=@talk.mp3     # to English
```
`model` is accepted and ignored (each capability has one model today).

## Jobs: everything, including video (they return at once; you poll)

```sh
curl https://api.wxch.org/v1/capabilities -H "Authorization: Bearer $KEY"     # what exists, its fields, whether a machine offers it now

# create (JSON; files go in as base64) or send multipart with fields "capability", "input" (JSON) and one file part per file field
curl https://api.wxch.org/v1/jobs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"capability":"video.generate","input":{"prompt":"waves on a beach","seconds":3,"size":"832x480"}}'
#   -> 201 {"id":"...","status":"queued", ...}
curl https://api.wxch.org/v1/jobs/$ID -H "Authorization: Bearer $KEY"        # status: queued | running | done | failed | cancelled
#   done: "outputs":[{"name":"out_00001.mp4","mime":"video/mp4","size":...,"url":"https://..."}]   (links valid for an hour)
curl https://api.wxch.org/v1/jobs -H "Authorization: Bearer $KEY"            # your own jobs
curl -X DELETE https://api.wxch.org/v1/jobs/$ID -H "Authorization: Bearer $KEY"   # cancel, or delete a finished job and its files
```
Capabilities and inputs (see `/v1/capabilities` for the exact fields and limits):

| capability | input |
|---|---|
| `image.generate` | `prompt`, `size`, `count`, `seed` |
| `image.edit` | file `image`, `prompt`, `quality` (fast/best), `seed` |
| `video.generate` | `operation` (text/image/story), `prompt`, file `image` (picture to video), `size`, `seconds` 1-20, `seed`; for `story`: `scenes` and `style` instead of `prompt`/`seconds` (see below) |
| `video.edit` | `operation` (upscale/interpolate), file `video`, `scale` 2/4, `multiplier` 2-4 |
| `audio.transcribe` | file `audio`, `language`, `task` (transcribe/translate) |

**Story (several scenes in one video).** The model makes about five seconds of one scene well and loses the picture when asked for much more, so a story is made scene by scene: each scene starts from the last picture of the one before, and the clips are joined into one video.

```sh
curl -s https://api.YOUR-DOMAIN/v1/jobs -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \n  -d '{"capability":"video.generate","input":{"operation":"story","style":"pastel colours, soft light",
       "scenes":[{"prompt":"a girl with long white hair walks down a pink hallway","seconds":4},
                 {"prompt":"she opens a door to a bedroom floating above the clouds","seconds":5}]}}'
```

`scenes`: 1-12 scenes, each `{prompt, seconds}` with 1-8 seconds (3-5 works best; default 5), at most 1500 characters per prompt. `style` is added to every scene (put the character and the look there once). The picture size limits the total length because the joined frames are kept in memory: 60 seconds at 832x480, about 26 seconds at 1280x704.

Limits: one key may have at most 5 jobs waiting or running; the whole queue holds 20; results are kept for 7 days; a job
made with a key is visible only to that key (the studio page shows only its own jobs).