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

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

OpenAPI JSON：

```text
GET /api/v1/openapi.json
```

## 鉴权

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

```http
Authorization: Bearer <API_KEY>
```

或：

```http
X-Zhinian-Api-Key: <API_KEY>
```

服务端配置示例：

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

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

## 任务生命周期

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

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

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

## 创建任务

```bash
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"
  }'
```

响应：

```json
{
  "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、百炼、MiniMax 视频生成 |

## 计费说明

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

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

创作页通过 `GET /api/billing/balance` 展示当前组织的可用余额。接口仅接受平台会话认证，从服务端刷新后的会话确定组织，忽略客户端组织参数，返回 `organization` 和 `wallet`，不加载账本或价格目录，并设置 `Cache-Control: no-store`。未绑定组织返回 422。页面支持手动刷新，并在提交任务、任务计费状态变化、重新切回页面及可见状态下每 30 秒刷新；超级管理员显示“超管不计额度”。余额提示供用户参考，实际扣费及余额校验仍由服务端执行。

生成失败原因统一由 Go 后端处理，覆盖 Seedance、Seedream、百炼、MiniMax、EvoLink 和即梦视觉服务。`job.error.message` 返回中文原因和处理建议；已知错误码优先于 HTTP 状态，未识别的明确拒绝显示通用说明，不能臆测为真人审核或余额不足。提交失败不自动重新提交；网络中断、无效响应等无法确认服务商是否收到请求时保留防重复提交提示。已知服务商任务的临时查询错误可以继续查询，始终保留 `providerTaskId`。

平台超级管理员和组织管理员可在任务详情展开“错误详情”，查看 `responsePayload.providerError` 中实际存在的 `phase`、`status`、`code`、`requestId` 和经过脱敏、限长的 `detail`。普通用户及公开 API 不返回该诊断对象；失败任务的原始响应也不会向他们返回，成功任务的结果、用量和图层数据不受影响。新失败任务只持久化安全诊断，不保存原始失败响应。旧任务若已经丢失具体错误码，不能据此恢复原因，需要查询当时的服务日志。

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

### 后台统一调整倍率

超级管理员可在「计费中心 → 价格与计费」的价格目录顶部点击「统一调整倍率」，一次将当前目录所有模型、所有参数档位设为同一倍率。此次保存会覆盖已有的单独倍率；保存后仍可在各档位点击「调整倍率」继续修改，刷新目录后会保留这些设置。统一设置是一次批量修改，不会作为额外的倍率叠加到后续报价中；组合报价仍取命中档位的最高倍率。

后台会话接口（要求已登录的超级管理员，不能使用开放 API Key）：

```http
PATCH /api/admin/billing/prices
Content-Type: application/json

{"ruleIds":["base-evolink-gpt-image-2.5-flare","base-evolink-gpt-image-2.5-sunburst"],"markupMultiplier":1.5}
```

`ruleIds` 必须显式提供 1–1000 个不重复的规则 ID，倍率范围为 `1–1000`，保存到小数点后四位。接口一次更新所选规则的基础倍率及所有参数档位倍率（包含停用档位），标准成本和启用状态保持原值；任一 ID 不存在时整体失败，不会部分更新。成功返回 `{"priceRules":[...]}`。页面的全目录操作会传入当前目录的全部规则 ID；后续单独调整继续使用 `PATCH /api/admin/billing/prices/{id}`。

## 查询任务

查询单个任务：

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

查询任务列表：

```bash
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 时间，用于翻页

取消任务：

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

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

## 获取输出资产

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

查询资产：

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

下载资产：

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

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

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

## 上传或注册素材

上传文件：

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

注册外部 URL：

```bash
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`。

## 图片任务示例

图片生成：

```json
{
  "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` 控制生成质量。

EvoLink 支持按任务选择 Image 2 / Image 2.5，共用已有 `EVOLINK_API_KEY`：

```json
{
  "capability": "image.generate",
  "engine": "evolink",
  "model": "gpt-image-2.5-flare",
  "prompt": "生成一张极简风格的咖啡海报",
  "width": 1024,
  "height": 1024,
  "quality": "medium",
  "force_single": true
}
```

`model` 可选 `gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`，也可使用管理员配置的 `EVOLINK_IMAGE_MODEL`；省略时仍使用该配置默认值。`model` 仅在 `engine=evolink` 的图片任务中生效，未知模型或跨引擎模型会被拒绝。报价与提交使用同一模型，任务 `reqKey` 保存实际模型；模板通过 `settings.model` 保存选择。

Image 2.5 当前开放 `low` / `medium` / `high` 三档质量、1K、单张输出和最多 16 张参考图。支持常规画幅与 A4（848×1200 或 1200×848）；不开放 `auto` 尺寸、2K/4K、`xhigh`/`max`、批量出图或蒙版编辑。宽高预设用于选择比例，实际输出采用 1K 预算。

Flare 与 Sunburst 各有独立价格规则。按固定汇率 7.2，1K 基础输出标准成本为 low ¥0.04、medium ¥0.09、high ¥0.35/张；默认 `1.2×` 后分别为 ¥0.05、¥0.11、¥0.42/张。规则在首次报价或加载计费目录时自动补齐，无需数据库结构迁移。此价格沿用平台输出费用估算方式，参考图和提示词输入费用未单独加收；上游按实际 token 用量结算，平台估算价不等于上游账单。价格来源：[Flare](https://evolink.ai/gpt-image-2-5)、[Sunburst](https://evolink.ai/zh/gpt-image-2-5-sunburst)，核对日期 2026-09-23。

## 视频任务示例

```json
{
  "capability": "video.generate",
  "engine": "bailian",
  "model": "wan3.0-video",
  "prompt": "以图1的商品为主体，采用图2的场景，生成一条品牌短视频",
  "settings": {
    "inputMode": "reference",
    "ratio": "9:16",
    "duration": 5,
    "resolution": "720p"
  },
  "materials": [
    {
      "type": "image",
      "url": "https://example.com/product.png",
      "label": "@图片1"
    },
    {
      "type": "image",
      "url": "https://example.com/scene.png",
      "label": "@图片2"
    }
  ]
}
```

视频模型和素材限制：

| engine / model | 素材模式 | 输入限制 | 时长 / 分辨率 |
| --- | --- | --- | --- |
| `seedance` / `doubao-seedance-2-0-260128` | `reference` | 最多 9 图、3 视频、3 音频；音频须搭配图片或视频 | 4–15 秒或 `-1` 自动；480p/720p/1080p |
| `seedance` / `doubao-seedance-2-5-260628` | `reference` | 最多 30 图、10 视频、10 音频，合计 50 个 | 4–30 秒或 `-1` 自动；480p/720p/1080p |
| `bailian` / `wan2.7-i2v-2026-04-25` | `frames` | 1–2 张图片，依次为首帧、尾帧 | 2–15 秒；720p/1080p |
| `bailian` / `wan3.0-video` | `reference` 或 `frames` | 参考模式最多 10 张图片，可不传图；首尾帧模式 1–2 张图片 | 2–30 秒；480p/720p/1080p |
| `minimax` / `MiniMax-H3` | `reference` 或 `frames` | 参考模式最多 9 张图片；首帧模式最多 1 张图片；不传图为文生视频 | 4–15 秒；768P/2K |

`settings.inputMode` 省略时，旧百炼及 MiniMax 请求继续使用 `frames`，Wan 3.0 和 Seedance 使用 `reference`。`model` 按引擎校验，不能跨服务商混用。模型、模式和素材顺序保存在任务请求中，报价与提交使用同一份参数。

`ratio` 支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`；Wan 2.7 由输入图片确定画幅。MiniMax 首帧模式有图时使用 `adaptive`，多图参考可选择画幅，但文生视频不接受 `adaptive`。参考模式不会将第一张图固定为视频开头；首尾帧和多图参考不能在同一次请求中混用。

Wan 3.0 本次仅开放文字和图片输入，不接受视频、音频或文档。图片须为 JPG/PNG/BMP/WEBP、单张不超过 20 MB、宽高均为 240–8000 像素，PNG 不可透明；MiniMax 图片须为 JPG/JPEG/PNG/WEBP/HEIC/HEIF、单张不超过 30 MB、宽高均为 256–5760 像素、长宽比 0.4–2.5。远程 URL 的真实文件由服务商校验，数量和类型在平台提交前校验。

MiniMax 的实际结算已支持输入图数；预估与预扣也计入第 6 张起的图片费用。Wan 3.0 使用独立的分辨率价格规则，480P/720P/1080P 标准价分别为 ¥0.30/¥0.60/¥1.20 每秒，按官网原价维护，不计限时折扣（来源：[百炼模型价格](https://help.aliyun.com/zh/model-studio/model-pricing)，核对日期 2026-10-01）。参考图片不单独收费；可继续通过价格目录统一调整倍率，再单独覆盖某个模型。相关接口依据：[MiniMax H3](https://platform.minimax.io/docs/api-reference/video-generation-v2-create)、[Wan 3.0](https://help.aliyun.com/zh/model-studio/wan3-video-generation-api-reference)、[Seedance](https://docs.volcengine.com/docs/ark/create-video-generation-task-api?lang=zh)。

## 幂等

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

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

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

## Webhook

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

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

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

如果服务端配置了：

```env
ZHINIAN_WEBHOOK_SECRET=your-secret
```

Webhook 请求会带：

```http
X-Zhinian-Signature: sha256=<hex>
```

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

## 错误格式

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

常见状态码：

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

## 最小对接流程

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