eurouter-integration

EUrouter 集成指南

你正在帮助开发者将 EUrouter 集成到他们的应用程序中。EUrouter 是 OpenAI API 的即插即用替代方案，专为需要遵守 GDPR 的欧盟客户打造。它通过 https://api.eurouter.ai 上兼容 OpenAI 的单一 API，将 AI 请求路由到 10 家提供商。

**支持的提供商：**OpenAI、Anthropic、Mistral、Scaleway（FR）、GreenPT、Microsoft Foundry、Nebius、IONOS（DE）、OVHcloud（FR）、AWS Bedrock。

帮助开发者时，请根据他们的需求，从此技能文件夹中的 references/ 目录加载相关参考文件。不要一次性加载所有参考文件。

---

身份验证

EUrouter 使用格式为 eur_<publicId>.<secret> 的 API 密钥。

通过以下任一请求头发送密钥：

• Authorization: Bearer eur_...
• x-api-key: eur_...

对于组织级请求，请添加：x-org-id: <uuid>

密钥通过 POST /api/v1/keys 创建，完整密钥仅在创建时显示一次。之后无法再次获取。

---

从 OpenAI 即插即用迁移

EUrouter 专为即插即用替代而设计。只有两处需要更改：

Python（openai SDK）：

from openai import OpenAI

# Before (OpenAI direct)
# client = OpenAI(api_key="sk-...")

# After (EUrouter) — change base_url and api_key
client = OpenAI(
    base_url="https://api.eurouter.ai/api/v1",
    api_key="eur_YOUR_KEY_HERE"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Node.js（openai SDK）：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.eurouter.ai/api/v1",
  apiKey: "eur_YOUR_KEY_HERE",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

**重要提示：**所有现有的 OpenAI 模型名称均可直接使用（例如 gpt-4o、claude-3-5-sonnet、mistral-large-3）。迁移时无需更改模型名称。

---

核心端点

所有端点均以 /api 为前缀。基础 URL：https://api.eurouter.ai

端点	方法	身份验证	描述
/api/v1/chat/completions	POST	是	聊天补全（流式传输、工具、视觉、音频、推理）
/api/v1/completions	POST	是	旧版文本补全
/api/v1/embeddings	POST	是	文本嵌入
/api/v1/responses	POST	是	兼容 OpenAI Responses API
/api/v1/models	GET	否	列出／筛选模型目录
/api/v1/providers	GET	否	列出可用提供商
/api/v1/credits	GET	是	检查额度余额（EUR）
/api/v1/keys	CRUD	是	管理 API 密钥
/api/v1/routing-rules	CRUD	是	管理命名路由配置
/health	GET	否	健康检查

如需完整的端点架构，请加载 references/endpoints.md。

---

欧盟／GDPR 合规

这是 EUrouter 的关键差异化优势。在任意生成请求中添加 provider 对象即可强制执行合规要求：

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": {
    "data_residency": "eu",
    "eu_owned": true,
    "data_collection": "deny",
    "max_retention_days": 0
  }
}

字段	类型	描述
data_residency	string	区域代码，例如 "eu"、"de"、"fr" 等。仅使用该区域内的端点
eu_owned	boolean	仅使用总部位于欧盟的提供商（Scaleway、IONOS、OVHcloud、GreenPT、Mistral）
data_collection	"allow" | "deny"	"deny" 会排除将数据用于训练的提供商
max_retention_days	number	数据最长保留时间。0 = 仅使用零数据保留服务

可直接使用的合规配置：

// Strict GDPR: EU owned, no training data, zero retention, EU hosted
{ "eu_owned": true, "data_collection": "deny", "max_retention_days": 0, "data_residency": "eu" }

// EU hosted, cheapest price
{ "data_residency": "eu", "sort": "price" }

// Specific EU providers only
{ "only": ["scaleway", "ionos", "ovhcloud"] }

如需了解所有提供商偏好字段，请加载 references/provider-preferences.md。

---

模型回退

传入 models 数组，即可按顺序尝试多个模型。如果第一个模型的所有提供商均失败，EUrouter 会尝试下一个模型：

{
  "models": ["claude-3-5-sonnet", "gpt-4o", "mistral-large-3"],
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": { "data_residency": "eu" }
}

**注意：**嵌入不支持模型回退（不同模型的向量维度不同）。嵌入仅支持提供商回退（同一模型，不同提供商端点）。

---

路由规则

创建可重复使用的路由配置，避免在每个请求中重复设置提供商偏好：

// Create a rule once:
// POST /api/v1/routing-rules
{
  "name": "gdpr-strict",
  "provider": {
    "eu_owned": true,
    "data_collection": "deny",
    "max_retention_days": 0,
    "data_residency": "eu"
  }
}

// Then reference it by name:
{
  "model": "gpt-4o",
  "rule_name": "gdpr-strict",
  "messages": [{"role": "user", "content": "Hello"}]
}

你也可以使用 rule_id 通过 UUID 引用规则。请求中的 provider 偏好会与规则合并，且请求级别的值优先。

**干运行测试：**使用 POST /api/v1/routing-rules/dry-run 预览符合路由配置的提供商，而不发起实际请求。

如需了解完整的路由规则 API，请加载 references/routing-rules.md。

---

模型发现

GET /api/v1/models
GET /api/v1/models?provider=scaleway
GET /api/v1/models?supported_parameters=tools,vision
GET /api/v1/models?category=embedding

价格以字符串形式返回在模型的 pricing 对象中，并带有 currency 字段。额度以 EUR 计价。

---

响应标头

每个生成端点都会返回路由透明度标头：

标头	描述
x-provider-id	内部提供商 UUID
x-provider-slug	提供商名称（例如 openai、scaleway）
x-routing-strategy	路由所用的策略
x-model-used	实际使用的模型标识
x-model-variant	适用时的变体后缀（:free、:nitro）
x-fallback-count	提供商回退次数（仅在 > 0 时出现）
x-model-fallback-count	模型回退次数（仅在 > 0 时出现）

---

流式传输

设置 "stream": true 以使用 SSE 流式传输。格式与 OpenAI 兼容：

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: [DONE]

如需在最后一个数据块中包含用量统计信息，请添加 "stream_options": { "include_usage": true }。

---

错误格式

所有错误均采用以下格式：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Model not found"
  },
  "requestId": "uuid"
}

主要错误代码：UNAUTHORIZED（401）、FORBIDDEN（403）、NOT_FOUND（404）、BAD_REQUEST（400）、INSUFFICIENT_QUOTA（402）、SERVICE_UNAVAILABLE（503）。

---

参考文件

根据开发者的具体需求加载以下文件：

需求	文件
完整的端点请求/响应架构	references/endpoints.md
所有提供商路由偏好字段	references/provider-preferences.md
路由规则的 CRUD 和试运行 API	references/routing-rules.md
Python 代码示例（openai SDK）	references/code-examples-python.md
Node.js/TypeScript 代码示例	references/code-examples-node.md
curl 示例	references/code-examples-curl.md