集成与 API

开发者

让内部服务或外部系统安全地创建任务、接收结果。

创建 API Key

进入页签，为 Key 选择工作区与权限范围。密钥以 zma_ 开头，创建后只显示一次，请立即保存。

携带密钥调用 API

所有 /v1 端点都通过 Authorization 请求头认证，无需其他签名步骤。

请求头

bash

Authorization: Bearer zma_你的密钥

创建任务

向 https://agent.zmzai.cloud/v1/tasks 发送 POST，workspace_id 与 prompt 必填。建议携带 Idempotency-Key（16–128 个可打印字符），重复提交相同请求不会创建重复任务。

curl

bash

curl -X POST https://agent.zmzai.cloud/v1/tasks \
  -H "Authorization: Bearer zma_你的密钥" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_20260825_001" \
  -d '{
    "workspace_id": "ws_xxx",
    "prompt": "分析本周销售数据并输出一份摘要报告",
    "title": "周报分析",
    "output_schema": {
      "type": "object",
      "properties": { "summary": { "type": "string" } },
      "required": ["summary"]
    }
  }'

响应（HTTP 202，任务已入队）

json

{
  "task_id": "task_xxx",
  "run_id": "run_xxx",
  "session_id": "ses_xxx",
  "status": "queued",
  "replayed": false
}

轮询任务结果

任务异步执行，轮询 GET /v1/tasks/{task_id} 直到 status 变为终态（succeeded / failed / cancelled）。响应中的 structured_output 会按创建时传入的 output_schema 返回结构化结果，artifacts 列出任务生成的文件。

curl

bash

curl https://agent.zmzai.cloud/v1/tasks/task_xxx \
  -H "Authorization: Bearer zma_你的密钥"

响应

json

{
  "id": "task_xxx",
  "workspace_id": "ws_xxx",
  "project_id": null,
  "title": "周报分析",
  "status": "succeeded",
  "output": "本周销售额环比增长 12%……",
  "structured_output": { "summary": "本周销售额环比增长 12%" },
  "run": { "id": "run_xxx", "status": "succeeded", "attempt": 1 },
  "artifacts": [
    { "id": "art_xxx", "title": "report.md", "url": "/api/v1/artifacts/art_xxx" }
  ]
}

错误处理

错误统一返回 { code, error } JSON，HTTP 状态码符合语义：

code	HTTP	说明
UNAUTHENTICATED	401	未登录
API_KEY_UNAUTHORIZED	401	API Key 无效或缺少所需权限
INVALID_BODY	400	请求体格式不正确
IDEMPOTENCY_KEY_REQUIRED	400	缺少 Idempotency-Key 请求头
WORKSPACE_NOT_FOUND	404	工作区不存在或无权访问
TASK_NOT_FOUND	404	任务不存在或无权访问
PROJECT_BUDGET_EXCEEDED	429	项目并发运行数达到上限
WEBHOOK_UNAUTHORIZED	401	Webhook 签名验证失败