> ## 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.

# 用 AI 编程助手接入

> 复制一段提示词到 Claude Code、Codex、Cursor 等编程助手，由它自动把 OmniRelay 接入你的项目。

编程助手可以替你完成接入。复制下面的提示词，在 Claude Code、Codex、Cursor 或类似工具中打开你的项目，粘贴作为请求即可。助手会阅读本文档、检查你的代码、配置 OpenAI 兼容客户端，并添加一个冒烟测试。

## 准备工作

1. 完成[开通账户](https://omnirelay.ai/docs/cn/quickstart/joining-the-beta.md)，并按[首次 API 调用](https://omnirelay.ai/docs/cn/quickstart/first-api-call.md)确认服务已开通。
2. 在 **API Keys** 创建 Key，设置所需模型范围、预算和到期时间。
3. 自己把 Key 写入项目的 `.env`（或终端环境变量）`OMNIRELAY_API_KEY`。**不要把 Key 粘贴到助手的对话中**：对话记录可能被保存或记录到日志。

## 提示词

> [!TIP]
>
> 点击代码块右上角的复制按钮。

```text 提示词 theme={null}
请把 OmniRelay API 接入这个项目。OmniRelay 是 OpenAI 兼容的 API 网关，
唯一需要的凭证是 OmniRelay API Key。

先阅读以下文档（Markdown 版本），以文档为准，不要依赖你对 OmniRelay
或其他服务商的已有印象：
- https://omnirelay.ai/docs/llms.txt（全部页面索引）
- 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

按以下步骤进行：

1. 检查项目：语言、框架，以及现有的 LLM 客户端（OpenAI SDK、LangChain、
   Vercel AI SDK、直接 HTTP 调用）。已有的就复用，否则为该语言添加官方
   OpenAI SDK。修改文件前先把方案告诉我。

2. 配置：从环境变量读取 OMNIRELAY_API_KEY、OMNIRELAY_BASE_URL（默认
   https://api.omnirelay.ai/v1）和 OMNIRELAY_MODEL。在 .env.example 中只写
   占位值，并确认 .env 已被 git 忽略。绝不硬编码、打印、记录或提交 Key，
   也不要让我把 Key 粘贴到对话里。Key 只能在服务端使用，不能放进浏览器或
   移动端代码。

3. 选择模型：不要猜测模型 ID。如果已设置 OMNIRELAY_API_KEY，调用
   GET {OMNIRELAY_BASE_URL}/models（免费），只选择 mode 为 "live" 的条目。
   使用某项功能前，先检查该模型的 capabilities（stream、tools、json_object、
   json_schema、responses）和 limits。如果无法获取 Key，保留 OMNIRELAY_MODEL
   由我填写。

4. 客户端：把 SDK 的 base URL 设为 OMNIRELAY_BASE_URL，并关闭自动重试
   （Python 用 max_retries=0，JavaScript 用 maxRetries: 0）。真实调用会计费，
   并在发送前预留余额，因此不要添加盲目重试。只对错误文档中标明不计费的
   错误码重试，429 需要退避。除非项目已使用 Responses API，否则使用 Chat
   Completions；使用 Responses 时发送 store: false 并带上完整对话
   （不支持 previous_response_id）。

5. 请求：优先使用 stream: true 和 stream_options.include_usage: true，并处理
   最后一个不含 choices 的 usage 数据块。max_completion_tokens 不要超过模型
   limits。不要把某一模型系列特有的参数照搬到其他模型。

6. 错误与可观测性：在日志中记录响应头 X-Request-ID 和结算费用
   cost_microusd（除以 1,000,000 得到美元）。根据 error.code 而不只是 HTTP
   状态码分支处理。401/403 的 Key 问题和 402 的余额或预算错误要清楚地返回给
   调用方，不要重试。

7. 验证：添加一个小型冒烟测试脚本，先列出模型，再发送一次简短的流式请求
   （max_completion_tokens 不超过 64）。真实调用会计费，运行前先征得我同意，
   且不要在 CI 中运行。

8. 最后给出总结：修改了哪些文件、我需要设置哪些环境变量、运行冒烟测试的
   命令。
```

## 接下来会发生什么

* 助手会先提出方案，再修改代码。请像审查其他改动一样审查它的 diff。
* 查询模型列表不计费；冒烟测试会发起一次小额付费调用，助手应在运行前征求你的同意。
* 冒烟测试失败时，在[错误处理](https://omnirelay.ai/docs/cn/general/errors.md)中查找 `error.code`，并保留 `X-Request-ID` 以便联系支持。

> [!NOTE]
>
> 助手会遵循提示词，但仍可能出错。请确认 Key 只从环境变量读取、自动重试已关闭，且所选模型出现在你自己的 `GET /v1/models` 列表中。

## 提示

* **其他工具**：提示词是纯文本，任何能读取网页并编辑文件的助手都可以使用。如果助手无法访问网址，可在相关页面用**复制页面**菜单复制内容，作为上下文粘贴给它。
* **更多功能**：需要图片、视频或管理 API 时，把相应页面加入文档列表，例如[图片生成与编辑](https://omnirelay.ai/docs/cn/images/image-generation.md)、[视频生成](https://omnirelay.ai/docs/cn/videos/video-generation.md)或[管理 API](https://omnirelay.ai/docs/cn/general/management-api.md)。
* **已有 OpenAI 代码**：通常只需修改 base URL、Key 和模型。可以要求助手把改动控制在这个范围内。

[首次 API 调用](https://omnirelay.ai/docs/cn/quickstart/first-api-call.md) · [对话补全](https://omnirelay.ai/docs/cn/llms/chat-completions.md) · [错误处理](https://omnirelay.ai/docs/cn/general/errors.md)


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