开发文档接入手册 01—07

从一次请求,
到稳定集成

理解输入、任务与结果之间的约定,让模型能力进入你的产品与工作流。

从这里开始

模型 API · MCP · ID Axis

01

先明确要完成什么。

接入不是从挑选参数开始,而是先确定业务需要的输入、产物和验收方式。一次设计生成、一次图生 3D 与一次指标生产,遵循相似的调用过程,拥有不同的结果标准。

  1. 01

    选择能力

    按任务类型确定输入与输出。

  2. 02

    提交任务

    从服务端创建请求,保存任务标识。

  3. 03

    消费结果

    处理终态,校验产物,再进入业务。

示例协议

以下路径、字段与状态用于说明接入方式,接入时以约定版本为准。示例域名不提供在线服务。

POST /v1/tasks · cURL
# Set the agreed base URL and a server-side credential first.
# The .invalid host is a placeholder, not a live service.
export IDENIFE_BASE_URL="https://api.example.invalid"
export IDENIFE_API_KEY="<server-side-credential>"

curl --request POST "$IDENIFE_BASE_URL/v1/tasks" \
  --header "Authorization: Bearer $IDENIFE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "capability": "design.generate",
  "input": {
    "prompt": "Design a low, elegant electric GT in liquid silver.",
    "constraints": {
      "view": "front_three_quarter",
      "material": "satin_metal"
    }
  },
  "output": {
    "format": "png"
  }
}'
202 / queued

任务被接受,只代表已进入处理流程。保存 task_id 后查询任务;收到 succeeded 再读取 result。

02

把身份留在服务端。

浏览器负责产品体验,业务服务负责身份、权限与调用。让前端调用你自己的业务接口,再由服务端连接模型能力,可以统一管理凭证与访问范围。

用户界面业务输入
你的业务服务身份 · 权限 · 日志
模型与能力 API任务与产物
请求中需要明确的内容
字段 / 约定作用处理方式
Authorization服务端身份使用约定的凭证方式。凭证存放在服务端环境配置或密钥管理服务中。
Content-Typeapplication/json请求体按约定结构编码;文件上传与任务创建分开约定。
request_id请求追踪将返回的请求标识关联到业务日志;记录状态和错误码,避免记录完整凭证与敏感输入。

正式接入还应明确:凭证如何签发与轮换、是否按项目授权、请求限额如何反馈。不要把演示中的 Bearer 写法理解为所有部署都采用同一套鉴权方式。

03

相同的任务外层,明确的能力输入。

把“选哪种能力”“给什么条件”“需要什么产物”分开表达。业务服务可以复用任务管理逻辑,具体能力保留自己的输入校验与验收标准。

capability
选择要执行的能力。
input
承载任务条件与资产引用。
output
声明需要的交付格式。

输入清楚,结果才有共同的判断依据。

能力输入与输出示例
能力标识主要输入结果形态
design.generate设计要求、材料与视角条件概念图像与资产描述
image.to_3d输入图像资产、输出格式三维网格与材质资产
data.metrics数据集引用、指标口径与维度指标定义与结构化结果

图像与数据集通过约定的资产引用传入。文件大小、媒体类型、访问有效期与数据权限应在创建任务前检查;三维网格输出也不等同于参数化 CAD 实体。

查看各项模型与能力
04

任务会继续,连接不必一直等待。

耗时任务适合拆成“提交、观察、取回结果”。页面不需要一直阻塞等待;任务标识连接业务记录、执行状态与最终产物。

queued

已接收,等待处理

running

正在执行能力

succeeded

产物已就绪

failed / cancelled

失败与取消都是终态。保留原因与任务标识,由业务逻辑决定下一步;不要无条件重新提交。

查看有上限的任务查询示例TypeScript
GET /v1/tasks/{task_id}
// Illustrative server-side TypeScript; adapt to the agreed contract.
async function waitForTask(taskId: string, signal: AbortSignal) {
  const baseUrl = process.env.IDENIFE_BASE_URL;
  const key = process.env.IDENIFE_API_KEY;
  if (!baseUrl || !key) throw new Error("Missing configuration");

  for (let attempt = 0; attempt < 20; attempt++) {
    signal.throwIfAborted();
    const response = await fetch(
      baseUrl + "/v1/tasks/" + encodeURIComponent(taskId),
      { headers: { Authorization: "Bearer " + key }, signal }
    );
    if (!response.ok) throw new Error("HTTP " + response.status);
    const task = await response.json();
    if (task.status === "succeeded") return task.result;
    if (["failed", "cancelled"].includes(task.status)) {
      throw new Error(task.error?.code ?? task.status);
    }
    await new Promise<void>((resolve, reject) => {
      const stop = () => {
        clearTimeout(timer);
        reject(signal.reason);
      };
      const timer = setTimeout(() => {
        signal.removeEventListener("abort", stop);
        resolve();
      }, 1500);
      signal.addEventListener("abort", stop, { once: true });
    });
  }
  throw new Error("Polling budget exceeded; preserve taskId");
}

超时不等于任务失败

本地等待超时,只说明本次观察结束。保存任务标识,后续继续查询已有任务,避免生成重复产物。

重试要有明确边界

限流时遵循服务端的等待提示并设置重试预算。创建请求是否可重试、是否支持幂等键,必须先由接口约定明确。

05

结果可消费,失败可判断。

业务不应从一段自由文本里猜测任务是否完成。状态、产物与异常分开返回,才能让展示、归档、重试与人工处理各自有据可依。

result.json
{
  "task_id": "task_demo_design_001",
  "status": "succeeded",
  "result": {
    "artifacts": [
      {
        "id": "asset_demo_001",
        "type": "image",
        "format": "png",
        "uri": "asset://demo/electric-gt.png"
      }
    ],
    "capability": "design.generate"
  },
  "request_id": "req_demo_001"
}
artifacts
用资产描述读取结果,区分格式、类型与访问位置。示例 asset:// 是引用占位符,不是下载地址。
error.code
用稳定错误码分支处理,面向用户展示合适的说明;不要依赖错误文本做程序判断。
retryable
表示该异常是否适合重试;仍须结合当前业务状态、重试预算与接口约定。
400 / 422检查请求结构与业务条件
401 / 403检查凭证与资源权限
429等待后再试,控制并发
5xx记录请求标识,按策略恢复

HTTP 状态与重试语义参考 RFC 9110

06

接口、工具与执行,各有边界。

模型 API 负责调用能力,MCP 负责以协议暴露工具和资源,ID Axis 负责组织推理与任务执行。三者可以组合,但不能互相替代。

MCP

让工具可以被发现和调用。

本组示例以 MCP 2025-11-25 为协议参考。客户端先协商能力,再通过 tools/list 发现工具,通过 tools/call 提交参数;资源读取使用 resources/read。

工具输入应遵循其 Schema。工具执行错误与协议错误分别处理;工具描述不授予业务权限。

MCP · Tools
ID Axis

让执行有上下文和状态。

ID Axis 统一组织多智能体推理、任务上下文、可用工具、执行预算与结果处理,让多步工作在明确边界内持续推进。

涉及业务写入时,应在执行层检查权限与必要确认。恢复任务前,需要区分“尚未执行”与“已执行但未收到结果”。

了解执行架构
07

把演示,变成可运行的业务。

代码能返回结果,只是开始。正式接入需要对权限、异常、产物与观察方式形成共同约定,让能力在你的业务环境中持续工作。

01

访问边界

服务端保管凭证,区分环境与业务权限;文件和结果的访问范围可控。

环境配置 · 权限清单
02

任务处理

创建、查询、超时与终态都有对应逻辑,页面关闭后仍能根据任务标识恢复查看。

状态转换 · 恢复流程
03

失败处理

区分输入问题与暂时性故障;重试设上限,避免不确定状态下重复创建有副作用的任务。

异常样例 · 重试策略
04

结果验收

验证格式、必要字段和资产可访问性;工业设计结果接入后续人工与工程校核流程。

验收规则 · 回归样例
05

运行观察

关联请求与任务标识,记录排队、执行和失败情况;约定保留周期与问题排查方式。

追踪日志 · 运行记录
下一步

带着一个真实任务,开始连接。

先在示例中看清请求与结果,再整理业务目标、运行环境和需要交付的产物。

本页示例版本: illustrative-v1

鲁ICP备2024109755号-2
可拖动移动。右键、长按或按 Shift+F10 可选择停靠位置。