# 服务地址与环境

Genesis 模型 API 与 Product API 使用不同的服务地址。调用前先确认目标 API，再从当前环境提供的开发者接入信息中复制完整 Base URL；不要用控制台网页地址、其他环境地址或另一类 API 的地址进行替换。

## 选择正确的 Base URL

| 调用目标 | Base URL 形态 | 在 Base URL 后追加 | 入口页面 |
| --- | --- | --- | --- |
| Genesis 模型 API | Genesis 控制台「使用」页提供的完整 Base URL；当前提供的值通常已包含 `/v1` | `/models`、`/chat/completions`、`/responses`、`/messages`、`/embeddings` 或 `/rerank` | [Genesis 模型 API](../genesis-model-api/index.md) |
| Product API | 当前环境提供的 Product API Base URL，本文假设已经包含 `/newmoi` | `/workspaces`、`/workflow/...`、`/agents/a2a` 等 Product 相对路径 | [开始使用 Product API](../product-api/getting-started.md) |

两类地址可能使用相同域名，也可能由不同网关提供。域名是否相同不代表认证方式、版本路径或响应格式可以共用。

## 拼接接口地址

将 Base URL 作为不可拆分的配置值保存，再追加接口页给出的相对路径。

Genesis 示例：

```bash
export GENESIS_BASE_URL='<Complete Genesis Base URL copied from the console>'

curl "$GENESIS_BASE_URL/models" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN"
```

Product API 示例：

```bash
export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'

curl "$PRODUCT_API_BASE_URL/workspaces" \
  -H "X-API-Key: $PRODUCT_API_KEY"
```

将 Genesis 控制台提供的 Base URL 作为完整值使用，不要自行删除或追加版本路径。Product API Base URL 必须包含 `/newmoi`；如果部署方给出的地址尚未包含该前缀，应先确认完整地址，而不是在业务代码中猜测。接口地址中出现两个连续的版本段或产品前缀，通常表示 Base URL 和相对路径拼接错误。

## 在不同环境之间切换

开发、预发布和生产环境的地址、凭据、工作区和资源 ID 相互独立。切换环境时，应同时更新以下配置：

| 配置 | 为什么需要一起更新 |
| --- | --- |
| Base URL | 请求必须进入目标环境的网关。 |
| 访问凭据 | 凭据由对应环境签发或授权，不能根据格式推断可以跨环境使用。 |
| `X-Workspace-ID` | Product 工作区 ID 属于当前环境。名称相同不代表 ID 相同。 |
| 模型或资源 ID | 模型可见范围和 Product 资源由当前环境决定。 |

建议让应用通过配置文件、部署变量或密钥管理服务注入这些值。不要在代码中通过替换域名字符串切换环境，这种做法容易保留错误的路径、凭据或资源 ID。

## 发送请求前检查

第一次接入或切换环境后，先执行只读请求：

- Genesis：调用 `GET /models`，确认响应包含当前凭据可用的模型；
- Product API：调用 `GET /workspaces`，确认响应包含当前账号可见的工作区。

只读检查成功后，再执行创建、运行、导入、发布或删除操作。这样可以先区分地址、认证和资源配置问题，避免在连接尚未确认时产生重复写入。

## 地址错误时检查

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 返回 `404` | Base URL 是否重复包含 `/v1` 或 `/newmoi`，相对路径是否属于当前 API | 从当前环境重新复制 Base URL，再按接口页追加相对路径。 |
| 返回网页 HTML | 是否使用了控制台网页地址，响应 `Content-Type` 是否为 `text/html` | 改用开发者接入信息提供的 API Base URL。 |
| 返回认证错误 | Base URL 和凭据是否来自同一环境，认证 Header 是否属于当前 API | 按[身份认证](authentication.md)重新选择凭据和 Header。 |
| 可以访问但找不到模型或资源 | 模型、工作区或资源 ID 是否来自另一环境 | 在当前环境重新列出模型或工作区，不复用历史 ID。 |

## 下一步

- [为当前 API 配置正确的身份认证](authentication.md)
- [了解不同接口的请求与响应格式](request-response-formats.md)
- [完成第一次 Product API 调用](../product-api/getting-started.md)