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

本文面向服务端对接方。所有开放接口位于 `/api/v1`，使用 API Key 鉴权。

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
}
```

### 支持的 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 时间，用于翻页

## 获取输出资产

任务成功后，`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,
  "force_single": true
}
```

智能超清：

```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
{
  "event": "generation.succeeded",
  "job": {
    "id": "job_xxx",
    "status": "succeeded",
    "outputAssetIds": ["asset_xxx"]
  }
}
```

如果服务端配置了：

```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` 查询并下载资产。