身份认证¶
Genesis 模型 API 与 Product API 使用不同的凭据和认证 Header。先确认调用目标，再只发送该接口要求的一种凭据；不要在两类 API 之间复用 Base URL、Header 或浏览器会话。
选择认证方式¶
调用目标 |
凭据 |
认证 Header |
额外作用域 |
|---|---|---|---|
Genesis 模型 API |
Genesis 可用的个人访问令牌或服务账号 API Key |
|
模型必须对当前凭据可见。完整规则见 Genesis 身份认证。 |
Product API |
UC 个人访问令牌（PAT） |
|
访问工作区资源时通常还需要 |
Product API 的 X-Workspace-ID 用于选择资源和权限作用域，不是第二个认证凭据。工作区发现接口 GET /workspaces 是例外，因为调用时还没有选定工作区。
调用 Genesis 模型 API¶
将当前环境提供的 Genesis Base URL 和访问凭据保存为环境变量：
export GENESIS_BASE_URL='<Complete Genesis Base URL copied from the console>'
export GENESIS_ACCESS_TOKEN='<Genesis access token>'
在请求中发送 Bearer 凭据：
curl "$GENESIS_BASE_URL/models" \
-H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
-H "Accept: application/json"
请求成功后，使用响应中的模型 ID 构造后续推理请求。不同协议的 SDK 参数和版本 Header 由对应 SDK 或接口页说明，不要从一个兼容接口类推到另一个接口。
调用 Product API¶
将 Product API Base URL 和 PAT 保存为环境变量：
export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'
从当前环境的开发者接入信息取得完整 Product API Base URL，从账号凭据管理入口创建或取得 PAT。Base URL 与 PAT 是两项独立配置，不能用控制台网页地址或 Genesis 凭据替代。
先列出当前账号可见的工作区：
curl "$PRODUCT_API_BASE_URL/workspaces" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "Accept: application/json"
选择工作区后，将返回的工作区 ID 用于后续资源请求：
export WORKSPACE_ID='<workspace-id-from-response>'
curl -X POST "$PRODUCT_API_BASE_URL/user/info" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Accept: application/json"
不要同时发送 Product PAT、Authorization Header 和浏览器 Cookie。多种凭据同时出现会使服务无法确定调用身份，并可能直接拒绝请求。
安全保存凭据¶
本地验证时，通过环境变量或本机密钥工具传入凭据；退出共享终端前清理相关变量。
在应用和 CI/CD 中，通过部署平台或密钥管理服务注入凭据，不写入应用代码、镜像和配置样例。
不在 URL、查询参数、日志、截图或错误报告中记录完整凭据。
轮换凭据时，先更新调用方并完成只读验证，再停用旧凭据。
不把浏览器 Cookie 当作服务端程序的长期凭据。
认证和权限失败时检查¶
HTTP 状态 |
先检查 |
下一步 |
|---|---|---|
|
Product 请求是否同时携带 |
只保留 Product PAT 的 |
|
凭据是否完整、有效并属于当前环境；Header 名称和 Bearer 格式是否正确 |
从当前环境重新取得或轮换凭据，先执行只读请求。 |
|
Genesis 模型是否对凭据可见；Product 工作区、角色和资源权限是否正确 |
使用模型列表或工作区列表确认作用域，再检查目标资源权限。 |
|
Base URL、路径和工作区是否属于当前环境 |
按服务地址与环境重新拼接请求。 |
认证成功只说明服务已经识别调用身份，不代表该身份拥有目标模型、工作区或资源的操作权限。收到 403 时不要反复轮换凭据，应先检查模型范围或 Product 资源授权。