311 lines
6.2 KiB
Markdown
311 lines
6.2 KiB
Markdown
# 智念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
|
||
```
|
||
|
||
冒号前是 clientId，冒号后是 API Key。任务和资产会按 clientId 做基本隔离。
|
||
|
||
## 任务生命周期
|
||
|
||
创建任务后不会同步生成结果，而是进入任务队列：
|
||
|
||
```text
|
||
queued -> running -> succeeded
|
||
-> failed
|
||
-> expired
|
||
-> cancelled
|
||
```
|
||
|
||
必须运行 Worker：
|
||
|
||
```bash
|
||
npm run worker
|
||
```
|
||
|
||
或 Docker Compose 中的 `zhinian-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` | 图片生成 |
|
||
| `image.inpaint` | 局部重绘 |
|
||
| `image.upscale` | 智能超清 |
|
||
| `video.generate` | Seedance 视频生成 |
|
||
|
||
## 查询任务
|
||
|
||
查询单个任务：
|
||
|
||
```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` 控制生成质量。
|
||
|
||
智能超清：
|
||
|
||
```json
|
||
{
|
||
"capability": "image.upscale",
|
||
"imageUrls": ["https://example.com/input.png"],
|
||
"resolution": "4k"
|
||
}
|
||
```
|
||
|
||
局部重绘：
|
||
|
||
```json
|
||
{
|
||
"capability": "image.inpaint",
|
||
"prompt": "把选中区域文字替换成新品上市",
|
||
"imageUrls": [
|
||
"https://example.com/original.png",
|
||
"https://example.com/mask.png"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 视频任务示例
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
## 幂等
|
||
|
||
建议所有创建任务请求都带：
|
||
|
||
```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` 查询并下载资产。
|