# Oh API

> Build AI character, digital-twin, chat, audio, image, and video experiences through a REST API.

Oh API uses the production base URL `https://api.oh.xyz`. Authenticate server-to-server requests with `X-API-Key`. Keep API keys in server-only environment variables and never expose them to browsers or mobile clients.

## Start here

- [Complete AI integration context](https://api.oh.xyz/llms-full.txt): Copyable quick start, outcome recipes, implementation patterns, and the full endpoint reference.
- [OpenAPI 3.0 specification](https://api.oh.xyz/openapi.json): Machine-readable schemas for all public operations.
- [Interactive documentation](https://api.oh.xyz/documentation): Browsable endpoint reference with copyable JavaScript, Python, and cURL examples.
- [API playground](https://api.oh.xyz/playground): Try supported generation flows.
- [API keys](https://api.oh.xyz/keys): Create and manage partner API keys.

## Essential implementation rules

- Store the key as `OH_API_KEY` on the server.
- Reuse rooms to preserve conversation context.
- Text and audio replies are synchronous.
- Image and video generation are asynchronous.
- Poll `GET /api/v1/jobs/{job_id}/status` until `completed` or `failed`.
- Use the final `url` from a completed job response.
- Retry transient `5xx` responses with backoff and surface upstream error details.

## Common outcomes

- Character chat: `GET /api/v1/customer-library` → `POST /api/v1/rooms` → `POST /api/v1/text`
- Spoken reply: `POST /api/v1/audio/notes`
- Image: `POST /api/v1/images` → poll job status
- Video: `POST /api/v1/videos/create` → poll the matching status endpoint
- Character creation: `POST /api/v2/characters/generate` → poll → review → save