# API 参考

Developer 与模型 API 的完整清单。机器可读版本：[`/developer/openapi.json`](https://www.ai-dc.ai/developer/openapi.json)（由服务端的契约注册表生成，与代码同步）。

## 约定

- 根地址 `https://www.ai-dc.ai`；路径都在 `/api/v1/**` 下，`v1` 内不做破坏性变更。
- 成功：`{ "ok": true, "data": …, "meta": { "requestId", "generatedAt", "version": "v1" } }`；失败：`{ "ok": false, "error": { "code", "message", "details" }, "meta": … }`。例外：OpenAI 兼容端点（`/chat/completions`、`/audio/transcriptions`、`/models`）成功时返回 OpenAI 的形状，失败仍是信封。
- 传 `x-request-id` 可以贯穿日志；响应头回同一个值。
- 写操作支持 `x-aidc-dry-run: true`（返回 202 + 计划，不落库）。

## 鉴权

| 凭证 | 形如 | 谁用 | 能做什么 |
| --- | --- | --- | --- |
| 开发者 Key | `aidc-dk-…` | CLI、服务端、智能体 | 发布应用、调模型与数据集（记 Key 所属公司） |
| 应用票据 | `aidc-at-…` | Nexus 应用里的浏览器 SDK（平台自动注入） | 只能调清单里声明的模型与数据集，按应用额度计量 |
| Agent Key | `aidc-sk-…` | 调智能体（Agent API） | 与某个智能体对话 |

`Authorization: Bearer <凭证>`。

## 端点

### 登录（设备授权，RFC 8628 语义）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/api/v1/developer/password-tokens` | 终端登录（`aidc login`）：`login` + `password`（+ `cellId`）→ `apiKey`（仅此一次）；能代表几家公司时 400 `company_required`（`details.companies`）；支持 dry-run |
| `POST` | `/api/v1/developer/device-codes` | 浏览器批准登录（`aidc login --browser`）：返回 `deviceCode`、`userCode`、`verificationUriComplete`、`interval` |
| `POST` | `/api/v1/developer/device-codes/decision` | （浏览器，已登录）批准 / 拒绝 |
| `POST` | `/api/v1/developer/device-tokens` | 轮询换 Key：`authorization_pending` → 成功返回 `apiKey`（仅此一次） |
| `GET` | `/api/v1/developer/me` | 当前身份 |
| `GET` | `/api/v1/developer/keys` | 本人的开发者 Key（只含前缀） |
| `DELETE` | `/api/v1/developer/keys/{keyId}` | 吊销（幂等） |

### 应用（发布 SDK）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/apps` | 列表 |
| `GET` | `/api/v1/developer/apps/{namespace}/{slug}` | 通道、版本、地址 |
| `POST` | `/api/v1/developer/apps/{namespace}/{slug}/versions` | 上传版本包（201 新建 / 200 已存在） |
| `POST` | `/api/v1/developer/apps/{namespace}/{slug}/channels/{channel}` | 晋升到 `test` / `production` |
| `POST` | `/api/v1/developer/apps/{namespace}/{slug}/tickets?channel=` | 应用票据续期 |
| `GET` | `/api/v1/developer/apps/{namespace}/{slug}/card` | [应用卡片](app-card)：负责部门、版本、SDK、连了哪些数据、对外能力与依赖 |

### 模型

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/models` | 目录（公开） |
| `GET` | `/api/v1/models/models` | OpenAI 形状的模型列表 |
| `POST` | `/api/v1/models/chat/completions` | OpenAI 兼容对话（文本 / 图片 / 流式 / 结构化） |
| `POST` | `/api/v1/models/audio/transcriptions` | OpenAI 兼容文件转写（multipart，≤ 4 MB） |
| `POST` | `/api/v1/models/realtime/transcription-sessions` | 实时转写票据（WebRTC 直连） |
| `POST` | `/api/v1/models/jev/decisions` | Jev 决策 |
| `POST` | `/api/v1/models/vision/detect` | 物体检测：一张图 → 类别 + 把握 + 归一化框（缺省 gpt-6-luna） |

### 建模（建模 SDK · 世界模型）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/modeling` | 目录（公开）：Marble 模型、价目（credits / USD）、当前策略、上游是否已配置 |
| `GET` | `/api/v1/developer/modeling/{namespace}/budget` | 本月额度：上限 / 已结算 / 进行中预留 / 剩余 |
| `GET` / `POST` | `/api/v1/developer/modeling/{namespace}/worlds` | 世界列表 / 生成（202；`Idempotency-Key` 必填；同样的请求复用已有世界；dry-run 给估价与额度） |
| `GET` / `DELETE` | `/api/v1/developer/modeling/{namespace}/worlds/{id}` | 详情（进行中会同步进度）/ 删除（`?purge=1` 同时删 World Labs 原件） |
| `PUT` | `/api/v1/developer/modeling/{namespace}/worlds/{id}/anchors` | 锚点（整组替换，`ifRev` 乐观并发，可绑语义层对象） |
| `POST` | `/api/v1/developer/modeling/{namespace}/worlds/{id}/exports` | 导出：`splats-ply`（免费）/ `mesh-glb`（3,500 credits，缺省关闭） |
| `POST` | `/api/v1/developer/modeling/{namespace}/media` | 上传输入：换 World Labs 签名地址，字节直传 |
| `POST` | `/api/v1/developer/modeling/{namespace}/imports` | 登记已有的 Marble 世界（AIDC 平台账号） |

`{namespace}` = `public`（任何人可读）或公司 cellId。见 [建模 SDK](modeling)。

### Semantic · Ontology（照 Palantir REST API v2；`{ontology}` = 公司 cellId）

Semantic 是数据平台（见 [Semantic](semantic.md)）：原来的连接、数据、权限、工作流、日志、账单六组接口都归到下面几节，路径不变。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/ontologies/{ontology}/fullMetadata` | 本体全貌：对象类型（含数据源 `datasources` 与同步进度）、链接、Action、接口、值类型 |
| `GET` | `/api/v1/ontologies/{ontology}/objectTypes`、`actionTypes`、`interfaceTypes`、`sharedPropertyTypes`、`valueTypes`、`queryTypes`（各带 `/{apiName}`） | 各类定义 |
| `GET` / `POST` | `/api/v1/ontologies/{ontology}/objects/{objectType}`、`…/search`、`…/aggregate`、`…/count` | 列对象 / 搜索 / 聚合 / 计数 |
| `GET` | `/api/v1/ontologies/{ontology}/objects/{objectType}/{primaryKey}`、`…/links/{linkType}` | 一个对象 / 沿链接走 |
| `POST` | `/api/v1/ontologies/{ontology}/objectSets/loadObjects`、`objectSets/aggregate`、`objectSets/createTemporary` | 对象集 |
| `POST` | `/api/v1/ontologySubscriptions/ontologies/{ontology}/streamSubscriptions` | 订阅对象集（SSE：`subscribeResponses`、`objectSetChanged`（`ADDED_OR_UPDATED` / `REMOVED`）、`refreshObjectSet`、`subscriptionClosed`；`after` 续传） |
| `POST` | `/api/v1/ontologies/{ontology}/actions/{action}/apply`、`…/applyBatch` | 执行 Action（改数据只走这一条） |
| `POST` | `/api/v1/ontologies/{ontology}/objectTypes/{objectType}/editsHistory` | 对象的每次修改 |
| `GET` / `POST` | `/api/v1/ontologies/{ontology}/branches/**`、`…/proposals/**` | 建本体：分支（modify / validate / conflicts / rebase）与提案；审核与合并由人做 |
| `POST` | `/api/v1/sqlQueries/executeOntology` | Ontology SQL（只读，一条 SELECT） |
| `GET` / `POST` | `/api/v1/ontologies/{ontology}/database`、`database/sync`、`database/credentials` | Semantic 数据库：表与列、同步、只读直连口令 |

### Semantic · 数据流与数据源（Data Connection）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` / `POST` | `/api/v1/developer/streams` | 数据流列表 / 声明（字段白名单、主键） |
| `GET` / `DELETE` | `/api/v1/developer/streams/{namespace}/{name}` | 信息 + 最新状态 / 删除（还是 Object Type 数据源的流 409 `stream_in_use`） |
| `GET` / `POST` | `/api/v1/developer/streams/{namespace}/{name}/events` | 订阅（SSE，`?after=` 续传）/ 发布（发布 Key `aidc-pk-…` 或开发者 Key） |
| `GET` / `POST` / `DELETE` | `/api/v1/developer/streams/{namespace}/{name}/keys` | 发布 Key：列表 / 签发 / 吊销 |
| `GET` / `POST` | `/api/v1/developer/data/{namespace}/bindings` | 各类型的数据源与同步进度 / 设数据源（改的是 Object Type 定义） |
| `POST` / `DELETE` | `/api/v1/developer/data/{namespace}/bindings/{id}` | 重同步 / 从定义里去掉 |
| `POST` | `/api/v1/ontologies/{ontology}/datasources/platform/sync` | 平台数据源立即同步：AIDC 平台对象类型；AIDC 组织另有 AIDC Ontology 的平台数据源与 AWS 数据源（`aidc semantic datasource sync`） |

### Semantic · 访问与账号（Filesystem、Admin）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/filesystem/resources`、`/{resourceRid}` | 看得见的资源、开放程度、我的角色 |
| `GET` / `POST` | `/api/v1/filesystem/resources/{resourceRid}/roles`、`roles/add`、`roles/remove` | Owner / Editor / Viewer（只有 Owner 改分享） |
| `POST` | `/api/v1/filesystem/resources/{resourceRid}/access` | 开放程度：Private / Group / Public / Open to Internet |
| `POST` / `DELETE` | `/api/v1/filesystem/resources/{resourceRid}/links`、`/{linkId}` | 邀请链接 |
| `GET` | `/api/v1/developer/auth/me` | 我是谁、角色、语义层权限 |
| `GET` / `POST` | `/api/v1/developer/shares` | 分享列表 / 分享 |
| `DELETE` | `/api/v1/developer/shares/{id}` | 撤销分享 |
| `GET` | `/api/v1/developer/members` | 本公司成员：角色、是否已激活 |
| `POST` | `/api/v1/developer/members/import` | 导入已有名单成为本公司 member（dry-run、幂等；developer 不降级） |

### Semantic · 自动化（Automate）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/capabilities/{namespace}` | 能力目录（已发布应用的显式导出 + 自动提取） |
| `GET` | `/api/v1/developer/workflows/{namespace}` | 工作流列表 |
| `GET` | `/api/v1/developer/workflows/{namespace}/{slug}?channel=` | 详情：编排计划、步骤、泳道、提供方卡片 |
| `GET` / `POST` | `/api/v1/developer/workflows/{namespace}/{slug}/runs` | 运行列表 / 开跑（202，`mode: run \| preview`，`Idempotency-Key`，dry-run） |
| `GET` | `/api/v1/developer/workflows/{namespace}/{slug}/runs/{id}` | 一次运行（每一步的状态、耗时、输出） |
| `GET` | `/api/v1/developer/workflows/{namespace}/{slug}/runs/{id}/events` | 实时进度（SSE：`run` → `done`） |

### Semantic · 应用日志与用量（Observability、Resource Management）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` / `POST` | `/api/v1/developer/log/{namespace}/events` | 查记录 / 记 usage、feedback、error |
| `PATCH` | `/api/v1/developer/log/{namespace}/events/{id}` | 反馈处理状态 |
| `GET` | `/api/v1/developer/log/{namespace}/summary` | 概况、版本状态、发布记录、语义版本 |
| `GET` | `/api/v1/developer/billing/prices` | 价目：计量方式、单价、来源（公开） |
| `POST` | `/api/v1/developer/billing/estimate` | 估算：每次 / 每天 / 每月多少钱、放不放得下预算 |
| `GET` | `/api/v1/developer/billing/{namespace}/summary` | 账单：今日 / 本月 / 累计，按应用 / Key / 模型 / 天，月底预测、预算、未计价 |
| `GET` | `/api/v1/developer/billing/{namespace}/records` | 台账明细（分页） |
| `GET` | `/api/v1/developer/billing/{namespace}/check` | 对账 |

### Semantic · 旧的语义与数据层接口（1.2.x，照样能用）

语义（`semantic.describe / define / action / publish`）：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/semantic/{namespace}` | 说明书：看得见的类型、属性、链接、Action、枚举、语义版本、给大模型的 markdown |
| `GET` / `POST` | `/api/v1/developer/semantic/{namespace}/types` | 全部定义（开发者）/ 一次定义一批（整批校验引用闭合，dry-run 同） |
| `GET` / `PUT` / `DELETE` | `/api/v1/developer/semantic/{namespace}/types/{apiName}` | 读 / 定义（有则改）/ 归档 |
| `POST` | `/api/v1/developer/semantic/{namespace}/actions/{apiName}` | 执行 Action |
| `GET` / `POST` | `/api/v1/developer/semantic/{namespace}/releases` | 语义版本 / 发布 |

数据层（`data.*`；改数据请用 Action）：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` / `POST` | `/api/v1/developer/data/{namespace}/objects/{type}` | 查询（`where` `sort` `limit` `offset`）/ 新建 |
| `GET` / `PATCH` / `DELETE` | `/api/v1/developer/data/{namespace}/objects/{type}/{pk}` | 读（`?link=` `?history=1`）/ 改（`set` `revert` `ifRev`）/ 删 |
| `POST` | `/api/v1/developer/data/{namespace}/aggregate/{type}` | 聚合 |
| `POST` | `/api/v1/developer/data/{namespace}/import/{type}` | 批量导入（≤ 5000 行） |
| `GET` | `/api/v1/developer/data/{namespace}/changes` | 变化订阅（SSE，`?after=` `?types=`） |

### Semantic · 数据集（旧：固定报告，只含聚合）

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/datasets` | 可读的数据集 |
| `GET` | `/api/v1/developer/datasets/{datasetId}/reports/{reportId}` | 固定报告（只含聚合） |

### 自进化、登记表

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/v1/developer/evolve/{namespace}/evidence` | 改进证据 |
| `POST` | `/api/v1/developer/evolve/{namespace}/suggest` | 模型起草提案 |
| `GET` / `POST` | `/api/v1/developer/evolve/{namespace}/proposals` | 提案 |
| `PATCH` | `/api/v1/developer/evolve/{namespace}/proposals/{id}` | 采纳 / 拒绝 |
| `POST` | `/api/v1/developer/evolve/{namespace}/proposals/{id}/apply` | 应用 |
| `GET` | `/api/v1/developer/evolve/{namespace}/apps/{slug}/overlay` | 应用里的改进：调用方看到的覆盖层（`?since=` 没变只回 `changed:false`） |
| `POST` | `/api/v1/developer/evolve/{namespace}/apps/{slug}/compile` | 一句话 → 改进指令（不落库） |
| `GET` / `POST` | `/api/v1/developer/evolve/{namespace}/apps/{slug}/improvements` | 改进工程列表 / 保存（幂等，dry-run） |
| `PATCH` | `/api/v1/developer/evolve/{namespace}/apps/{slug}/improvements/{id}` | 提交 / 采纳 / 不采纳 / 撤销 |
| `GET` | `/api/v1/developer/registry` | 应用登记表 |

`{namespace}` = 公司 cellId（`cell-…`），必须是凭证所属的公司。1.22.0 起自提升并进自进化：旧路径 `/api/v1/developer/improve/{namespace}/…`（提案那一半）与 `/api/v1/developer/evolve/{namespace}/{slug}/…`（应用里的改进，现在在 `/apps/{slug}/` 下）照样能用，响应带 `Deprecation` 与指向新路径的 `Link`。

## 错误码（节选）

| 码 | HTTP | 含义 |
| --- | --- | --- |
| `unauthorized` | 401 | 没带凭证或凭证无效 / 已吊销 / 已过期 |
| `forbidden` | 403 | 没有权限（例如清单没声明这个模型） |
| `rate_limited` | 429 | 太频繁，`details.retryAfterSeconds` |
| `quota_exhausted` | 429 | 应用当日额度用完 |
| `invalid_payload` / `bundle_invalid` | 400 | 请求或版本包不合法，`details.issues` |
| `app_not_found` / `app_version_not_found` | 404 | 应用 / 版本不存在 |
| `version_not_tested` | 409 | 发布没进过 test 的版本 |
| `authorization_pending` / `device_code_expired` / `access_denied` | 400 / 403 | 设备授权的轮询状态 |
| `model_not_found` / `model_upstream_failed` | 404 / 502 | 模型不在目录 / 上游故障 |