API 参考
Developer 与模型 API 的完整清单。机器可读版本：/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 |
应用卡片：负责部门、版本、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。
Semantic · Ontology（照 Palantir REST API v2；{ontology} = 公司 cellId）
Semantic 是数据平台（见 Semantic）：原来的连接、数据、权限、工作流、日志、账单六组接口都归到下面几节，路径不变。
| 方法 |
路径 |
说明 |
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 |
模型不在目录 / 上游故障 |
本页由 developer/docs/api.md 生成 · Markdown 原文 · llms.txt