> ## Documentation Index
> Fetch the complete documentation index at: https://omnirelay.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up with an AI agent

> Copy one prompt into Claude Code, Codex, Cursor or another coding agent and let it add OmniRelay to your project.

Coding agents can do the integration for you. Copy the prompt below, open your project in Claude Code, Codex, Cursor or a similar agent, and paste it as your request. The agent reads these docs, inspects your code, wires up an OpenAI-compatible client and adds a smoke test.

## Before you start

1. Finish [Creating an account](https://omnirelay.ai/docs/quickstart/joining-the-beta.md) and confirm activation as described in [First API call](https://omnirelay.ai/docs/quickstart/first-api-call.md).
2. Create an API key under **API Keys** with the models, budget and expiry you want.
3. Put the key in your project's `.env` (or your shell) yourself as `OMNIRELAY_API_KEY`. **Do not paste the key into the agent's chat**: chat transcripts may be stored or logged.

## The prompt

> [!TIP]
>
> Use the copy button in the top right corner of the block.

```text Prompt theme={null}
Integrate the OmniRelay API into this project. OmniRelay is an OpenAI-compatible
API gateway; the only credential needed is an OmniRelay API key.

Read these docs first (Markdown versions) and trust them over your prior
knowledge of OmniRelay or of other providers:
- https://omnirelay.ai/docs/llms.txt (index of all pages)
- https://omnirelay.ai/docs/quickstart/first-api-call.md
- https://omnirelay.ai/docs/llms/listing-models.md
- https://omnirelay.ai/docs/llms/chat-completions.md
- https://omnirelay.ai/docs/general/errors.md

Work through these steps:

1. Inspect the project: language, framework and any existing LLM client
   (OpenAI SDK, LangChain, Vercel AI SDK, raw HTTP). Reuse what exists;
   otherwise add the official OpenAI SDK for this language. Show me the plan
   before changing files.

2. Configuration: read OMNIRELAY_API_KEY, OMNIRELAY_BASE_URL (default
   https://api.omnirelay.ai/v1) and OMNIRELAY_MODEL from the environment.
   Add them to .env.example with placeholder values only and make sure .env
   is git-ignored. Never hardcode, print, log or commit the key, and never ask
   me to paste it into this chat. The key is server-side only: never put it in
   browser or mobile code.

3. Model choice: do not guess model IDs. If OMNIRELAY_API_KEY is set, call
   GET {OMNIRELAY_BASE_URL}/models (free) and choose only an entry with
   mode "live". Before using a feature, check that model's capabilities
   (stream, tools, json_object, json_schema, responses) and limits. If the key
   is not available, leave OMNIRELAY_MODEL for me to fill in.

4. Client: set the SDK base URL to OMNIRELAY_BASE_URL and disable automatic
   retries (max_retries=0 in Python, maxRetries: 0 in JavaScript). Live calls
   are paid and reserve balance before dispatch, so never add blind retries.
   Retry only for the error codes the errors page marks as not charged, with
   backoff for 429s. Use Chat Completions unless the project already uses the
   Responses API; for Responses send store: false and the full conversation
   (previous_response_id is unsupported).

5. Requests: prefer stream: true with stream_options.include_usage: true and
   handle the final usage chunk, which has no choices. Set
   max_completion_tokens within the model's limits. Do not copy options that
   are specific to one model family to other models.

6. Errors and observability: log the X-Request-ID response header and the
   settled cost_microusd (divide by 1,000,000 for USD). Branch on
   error.code, not the HTTP status alone. Surface 401/403 key problems and
   402 balance or budget errors to the caller clearly instead of retrying.

7. Verification: add a small smoke-test script that lists models and sends
   one short streamed request (max_completion_tokens 64 or less). Live calls
   are charged, so ask me before running it, and do not run it in CI.

8. Finish with a summary: files changed, environment variables I need to set,
   and the command that runs the smoke test.
```

## What to expect

* The agent proposes a plan first, then edits your code. Review the diff as you would any other change.
* Listing models is free; the smoke test makes one small paid call, and the agent should ask before running it.
* If the smoke test fails, look up the `error.code` in [Errors](https://omnirelay.ai/docs/general/errors.md) and keep the `X-Request-ID` for support.

> [!NOTE]
>
> Agents follow the prompt but can still make mistakes. Check that the key is read only from the environment, that automatic retries are off, and that the chosen model appears in your own `GET /v1/models` list.

## Tips

* **Other tools**: the prompt is plain text, so it works with any agent that can read web pages and edit files. If your agent cannot fetch URLs, use the **Copy page** menu on the linked pages and paste them in as context.
* **More features**: for images, video or the Management API, add the relevant page to the list, for example [Image generation](https://omnirelay.ai/docs/images/image-generation.md), [Video generation](https://omnirelay.ai/docs/videos/video-generation.md) or [Management API](https://omnirelay.ai/docs/general/management-api.md).
* **Existing OpenAI code**: usually only the base URL, key and model change. Ask the agent to keep the change that small.

[First API call](https://omnirelay.ai/docs/quickstart/first-api-call.md) · [Chat completions](https://omnirelay.ai/docs/llms/chat-completions.md) · [Errors](https://omnirelay.ai/docs/general/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.