# Endpoint reference

Base URL `https://api.openmayhem.ai/v1`. Auth: `Authorization: Bearer sk-om-v1-...` on every
endpoint. Required scope in parentheses.

## Text

| Method + path | Purpose |
| --- | --- |
| `POST /chat/completions` (CHAT) | OpenAI-compatible chat completion, streaming optional |
| `POST /completions` (COMPLETIONS) | Legacy text completion |
| `POST /responses` (RESPONSES) | Stateless responses API |
| `POST /embeddings` (EMBEDDINGS) | Embedding vectors |

## Media jobs

| Method + path | Purpose |
| --- | --- |
| `POST /images/generations` (IMAGES) | Image generation job |
| `POST /videos` (VIDEOS) | Video generation job |
| `POST /audio/speech` (AUDIO_SPEECH) | Text-to-speech job |
| `POST /audio/transcriptions` (AUDIO_TRANSCRIPTIONS) | Speech-to-text job |
| `POST /audio/generations` (AUDIO_GENERATIONS) | Audio generation job |
| `POST /music/generations` (MUSIC) | Music generation job |
| `POST /workflows` (WORKFLOWS) | ComfyUI workflow-graph job |
| `GET /jobs` | List recent jobs |
| `GET /jobs/{id}` | Poll job status, cost, artifacts |
| `DELETE /jobs/{id}` | Cancel a running job |
| `GET /artifacts/{id}` | Download a job artifact (30-day retention) |

## Catalog and usage

All `/models*` routes are public, no key needed.

| Method + path | Purpose |
| --- | --- |
| `GET /models` | Public model catalog with prices and availability |
| `GET /models/by-id?id={id}` | Model detail: pricing, parameters, request contracts |
| `GET /models/by-id/stats?id={id}` | Throughput and latency statistics |
| `GET /models/by-id/activity?id={id}` | Recent request activity |
| `GET /models/by-id/availability?id={id}` | Provider availability history |
| `GET /models/by-id/pricing-history?id={id}` | Every published price version |
| `GET /requests/{id}` (CHAT) | Settled usage, cost and receipt for one request |

Pass the exact model id in the `id` query parameter. This safely supports
`vendor/model` ids without putting encoded separators in the URL path.

## Conventions

- `Idempotency-Key` header makes POST retries safe.
- `openmayhem.request_id` in the body identifies every request; streaming
  responses also send an `x-request-id` header.
- Every authenticated response carries `X-RateLimit-Limit` and
  `X-RateLimit-Remaining`; hitting the limit returns 429 with
  `Retry-After` seconds.
- Errors: JSON envelope with stable `code` (see Errors).
- Amounts are USD; the ledger uses micro-USD strings (1,000,000 = $1).
- Machine-readable spec: https://openmayhem.ai/openapi.json