wangxuming/NianAIGC

Fork 0

Files

inman 6480e503eb production runtime and mock removal

2026-08-17 23:44:14 +08:00

8.0 KiB

Raw Blame History

智念AIGC平台开放 API 对接说明

本文面向服务端对接方。所有开放接口位于 /api/v1，使用 API Key 鉴权；浏览器后台的 SSO 登录不会影响这些服务端接口。

OpenAPI JSON：

GET /api/v1/openapi.json

鉴权

支持两种方式，任选一种：

Authorization: Bearer <API_KEY>

或：

X-Zhinian-Api-Key: <API_KEY>

服务端配置示例：

ZHINIAN_API_KEYS=partner-a:key-a,partner-b:key-b

冒号前是账号 ID（兼容字段名 clientId），冒号后是 API Key。任务和资产会按账号 ID 写入独立数据分区，后端 owner 形如 api:partner-a。

任务生命周期

创建任务后不会同步生成结果，而是进入任务队列：

queued -> running -> succeeded
                  -> failed
                  -> expired
                  -> cancelled

Go API 内嵌 WorkerLoop，生产和 Docker Compose 都由 zhinian-go-api 进程负责领取、提交、轮询和结算任务；不再运行独立 Node Worker 服务。

创建任务

curl -X POST https://你的域名/api/v1/jobs \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-job-001" \
  -d '{
    "capability": "image.generate",
    "prompt": "生成一张专业产品主图",
    "width": 1440,
    "height": 2560,
    "webhookUrl": "https://example.com/zhinian/webhook"
  }'

响应：

{
  "job": {
    "id": "job_xxx",
    "capability": "image.generate",
    "status": "queued",
    "outputAssetIds": []
  },
  "reused": false
}

新建任务返回 202；如果命中相同 Idempotency-Key 的已创建任务，返回 200 且 reused: true。

支持的 capability

capability	说明
`image.generate`	图片生成
`video.generate`	Seedance 视频生成

计费说明

开放 API 仍按 API Key 和账号分区运行。当前未绑定组织的开放 API 任务保持兼容，不从组织钱包扣费；平台浏览器用户的真实图片/视频任务会按超级管理员配置的服务商标准单价、计费单位和上浮倍率，从所属组织余额冻结。普通用户余额不足时不会提交服务商并返回余额不足错误；超级管理员仍保存计算费用，但不检查、冻结或扣减组织额度，也不产生钱包扣费、退款流水。计费规则与最终金额会随任务保存，任务失败、取消或过期后由 Worker 在最终终态退款；Seedance 成功后按 usage.completion_tokens 多退少补，缺少该字段时保留冻结金额。

组织余额当前只能由超级管理员通过 /billing 的“余额与上账”直接入账。所有充值和人工余额调整都只记入组织账本，不存在个人上账归属；组织管理员和员工共同使用组织额度。未来接入支付时，支付成功回调应使用同一幂等上账逻辑自动入账，不产生待审核申请。余额不足时，平台会拒绝创建真实计费任务并返回错误；未配置真实服务商凭据时也不会生成占位结果。

首次加载超管计费中心或提交真实任务时会自动补齐内置标准成本目录，默认倍率为 1.2×，已有同服务商/能力/模型/变体规则会同步平台维护的标准成本与参数档案，但保留已配置倍率。视频规则按分辨率匹配 resolution=480p|720p|1080p|4k；参数化规则按服务下的参数维度选择档位，标准成本为基础成本乘以各档位系数，组合倍率取所选档位中的最高倍率；最终金额使用整数分并向上取整。EvoLink 默认按固定 1 USD = 7.20 CNY 换算，并列出质量、分辨率、画面比例和参考图数量档位；即梦 4.6 使用公开资源包折算值作为平台维护的参考标准，实时价格以火山控制台为准。超级管理员只调整倍率，标准成本和参数档案不通过后台修改。

查询任务

查询单个任务：

curl -H "Authorization: Bearer <API_KEY>" \
  https://你的域名/api/v1/jobs/job_xxx

查询任务列表：

curl -H "Authorization: Bearer <API_KEY>" \
  "https://你的域名/api/v1/jobs?status=succeeded&limit=20"

可用筛选：

status：queued、running、succeeded、failed、expired、cancelled
capability：见上表
limit：1 到 200
before：ISO 时间，用于翻页

取消任务：

curl -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  https://你的域名/api/v1/jobs/job_xxx/cancel

仅排队中或运行中的任务会被置为 cancelled；已进入终态的任务会原样返回。

获取输出资产

任务成功后，job.outputAssetIds 会包含输出资产 ID。

查询资产：

curl -H "Authorization: Bearer <API_KEY>" \
  https://你的域名/api/v1/assets/asset_xxx

下载资产：

curl -L \
  -H "Authorization: Bearer <API_KEY>" \
  -o result.png \
  https://你的域名/api/v1/assets/asset_xxx/download

也可以查询当前 API client 可访问的资产列表：

curl -H "Authorization: Bearer <API_KEY>" \
  https://你的域名/api/v1/assets

上传或注册素材

上传文件：

curl -X POST https://你的域名/api/v1/assets \
  -H "Authorization: Bearer <API_KEY>" \
  -F "files=@./reference.png"

注册外部 URL：

curl -X POST https://你的域名/api/v1/assets \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/reference.png",
    "name": "reference.png",
    "kind": "image"
  }'

返回的资产 ID 可放入后续任务的 inputAssetIds，资产 URL 可放入 inputUrls 或 imageUrls。

图片任务示例

图片生成：

{
  "capability": "image.generate",
  "prompt": "参考 @图片1 的风格，生成 9:16 旅游海报",
  "imageUrls": ["https://example.com/reference.png"],
  "width": 1440,
  "height": 2560,
  "scale": 50,
  "quality": "medium",
  "force_single": true
}

图片生成参数会按当前引擎生效：即梦使用 scale 控制文本影响，EvoLink 使用 quality 控制生成质量。

视频任务示例

{
  "capability": "video.generate",
  "prompt": "生成一条 9:16 品牌短视频，节奏明快，适合信息流投放",
  "settings": {
    "ratio": "9:16",
    "duration": 5,
    "resolution": "720p"
  },
  "materials": [
    {
      "type": "image",
      "url": "https://example.com/product.png",
      "label": "@图片1"
    }
  ]
}

视频参数限制：

duration：4 到 15 秒
ratio：16:9、4:3、1:1、3:4、9:16、21:9、adaptive
resolution：480p、720p、1080p、4k

幂等

建议所有创建任务请求都带：

Idempotency-Key: <业务唯一请求ID>

同一个 API client 使用相同 key 和相同请求体会返回已有任务；相同 key 但请求体不同会返回 409。

Webhook

创建任务时传 webhookUrl。任务进入终态后会回调：

{
  "jobId": "job_xxx",
  "status": "succeeded",
  "capability": "image.generate",
  "outputAssetIds": ["asset_xxx"],
  "updatedAt": "2026-06-08T12:00:00.000Z"
}

如果任务失败，payload 会包含 error。

如果服务端配置了：

ZHINIAN_WEBHOOK_SECRET=your-secret

Webhook 请求会带：

X-Zhinian-Signature: sha256=<hex>

签名内容是原始请求体 HMAC-SHA256。

错误格式

{
  "error": "Invalid API key."
}

常见状态码：

400：请求参数错误
401：API Key 缺失或错误
404：任务或资产不存在，或不属于当前 API client
409：幂等 key 冲突
500：服务端错误或 Worker token 配置错误

最小对接流程

运维提供域名和 API Key。
对接方调用 GET /api/v1/capabilities 确认能力。
对接方上传素材或注册外部 URL。
对接方调用 POST /api/v1/jobs 创建任务。
对接方轮询 GET /api/v1/jobs/:id，或等待 Webhook。
任务成功后用 outputAssetIds 查询并下载资产。

8.0 KiB Raw Blame History Unescape Escape