通用约定 API¶
本页说明 AI Studio Product API 的共通规则。具体请求字段、响应结构、限额与可选项， 以目标部署发布的 OpenAPI 为准。
Base URL 与路径写法¶
请求应发送到 AI Studio 界面使用的产品端点：
{product-endpoint}/{route}
本文中的 :id、:workflow_id 等片段表示路径参数，需要用经过 URL 编码的实际标识
整体替换。本文列出的产品路径均应保留 /newmoi 前缀。
认证¶
认证 Header 和凭据由目标部署发布的 OpenAPI 或资源调用面板确定。发起请求前，先从该部署复制完整的产品端点、Header 名称和值；每次请求只使用该操作显示的一组凭据。
不要混用 Genesis 模型凭据、从其他环境复制的浏览器 Cookie 或
MOI_SYSTEM_API_KEY。调用仍受工作区授权和审计控制；不要从其他资源、SDK 或历史示例推断认证方式。
工作区上下文¶
资源操作需要显式指定工作区：
X-Workspace-ID: <workspace-id>
工作区发现和创建是例外，因为调用时尚未选定工作区。客户端不能静默使用默认工作区； 从一个工作区取得的资源 ID，也不能证明调用者可以在另一个工作区访问它。
JSON、上传与下载¶
JSON 请求使用 Content-Type: application/json。文件上传接口可能接收 multipart，
也可能先返回部署环境签发的上传地址；文件预览、流式读取、导出和查询结果接口可能返回
二进制、数据流或临时 URL。应按响应的 Content-Type 处理，不能假定所有成功响应
都是 JSON。
密钥应放在 Header 或部署契约定义的密钥引用字段中。不要记录 API Key、Provider 凭据、连接器密码、会话 Cookie、预签名 URL，或包含这些内容的完整请求体。
返回结果与长任务¶
写操作成功后，可能返回资源、操作记录，也可能只返回成功包络。不要根据名称或空响应 自行推导 ID；后续调用前，应通过列表或详情接口读取服务端生成的资源标识。
导入、导出、工作流、知识来源处理、SQL、计算资源和 Agent 操作可能在首个 HTTP 响应 后继续执行。保留返回的任务、执行、查询或请求 ID，并查询对应状态接口，直到契约定义的 终态。A2A 或 Explore 流应在收到协议终止事件或调用者主动取消时结束。
分页与筛选¶
列表接口没有统一的请求形式：有的使用 Query 参数，有的使用 JSON 筛选体。应保留 服务端返回的 cursor、page、size、total 或 continuation 值，并按部署契约翻页。 除非接口明确保证排序，否则不能把第一项当作最新记录，也不能据此断定名称唯一。
错误与重试¶
状态码 |
含义 |
调用方处理 |
|---|---|---|
|
参数或业务校验失败 |
修正提示字段，不要原样重试 |
|
身份缺失、无效或过期 |
刷新或更换调用凭据 |
|
当前身份无权执行工作区或资源操作 |
检查工作区、角色和资源授权 |
|
资源不存在或对调用者不可见 |
核对资源 ID 与工作区 |
|
状态或版本冲突 |
重新读取最新状态后再提交 |
|
触发限流 |
优先遵循 |
|
服务错误或暂不可用 |
保留请求 ID，只进行有限次数重试 |
只重试安全读取和明确支持幂等的操作。重试创建、运行、发布、导入、导出或 SQL 执行前， 应先用已返回的操作 ID 查询，或使用接口明确支持的幂等键。网络超时并不能证明写入失败。
排障时记录 HTTP 状态、服务端 request/correlation ID、工作区 ID、路径、方法与时间； 分享诊断信息前必须移除凭据和业务数据。