素材库 (Asset Library)

素材库允许您将图片或视频注册为 Ark 素材，并通过 asset:// 协议在视频生成任务中复用，无需每次传入公网 URL。本地文件仅在上游处理期间由 SuanYuan 提供不可预测的临时 HTTPS 下载地址；素材处理结果与引用能力由 Ark 上游维护。

概念

概念	说明
素材分组 (`asset-group`)	素材的容器，用于按项目或场景隔离；一个分组可包含多个素材
素材 (`asset`)	一张图片或一段视频；上传后经过异步处理，状态变为 `active` 后即可引用
素材引用 (`reference`)	格式 `asset://{asset_id}`；图片用在 `image_url`，视频用在 `video_url`

工作流程

1. 创建素材分组          → 获得 group_id
2. 上传图片/视频到分组   → 获得 asset_id（状态为 processing）
3. 轮询素材状态          → 等待变为 active
4. 在视频生成中引用素材  → 图片传 image_url，视频传 video_url

鉴权

所有素材接口使用与其他 API 相同的 Bearer Token 鉴权：

http

Authorization: Bearer sk-your-api-key

接口列表

方法	路径	说明
`POST`	`/v1/asset-groups`	创建素材分组
`GET`	`/v1/asset-groups`	列出所有素材分组
`GET`	`/v1/asset-groups/{group_id}`	查询素材分组详情
`DELETE`	`/v1/asset-groups/{group_id}`	删除素材分组（同时删除组内素材）
`POST`	`/v1/assets`	通过公网 URL 创建素材
`POST`	`/v1/assets/uploads`	上传本地文件创建素材
`GET`	`/v1/assets`	列出素材
`GET`	`/v1/assets/{asset_id}`	查询素材详情与状态
`DELETE`	`/v1/assets/{asset_id}`	删除素材

1. 创建素材分组

bash

API_BASE='https://suanyuan.goesai.com'
API_KEY='sk-your-api-key'

curl -X POST "${API_BASE}/v1/asset-groups" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "产品素材",
    "description": "产品宣传视频参考图"
  }'

请求参数：

字段	类型	必填	说明
`name`	string	是	分组名称，最长 64 字符
`description`	string	否	分组描述
`group_type`	string	否	默认 `AIGC`；当前仅支持此类型

响应示例：

json

{
  "id": "group-abc123",
  "name": "产品素材",
  "group_type": "AIGC",
  "status": "active"
}

2. 列出素材分组

bash

curl "${API_BASE}/v1/asset-groups" \
  -H "Authorization: Bearer ${API_KEY}"

响应示例：

json

{
  "data": [
    {
      "id": "group-abc123",
      "name": "产品素材",
      "group_type": "AIGC",
      "status": "active"
    }
  ]
}

3. 创建素材（URL 方式）

将一张公网可访问的图片或视频注册为素材。URL 必须使用 HTTPS、使用标准 443 端口、由公网域名提供，且不能依赖登录、Cookie 或一次性签名链接。

bash

curl -X POST "${API_BASE}/v1/assets" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "group-abc123",
    "url": "https://example.com/product-front.png",
    "asset_type": "image",
    "name": "产品正面图"
  }'

请求参数：

字段	类型	必填	说明
`group_id`	string	是	目标素材分组 ID
`url`	string	是	素材公网 HTTPS URL。视频应为可直接下载的 MP4 URL
`asset_type`	string	是	`image` 或 `video`
`name`	string	否	素材显示名称

响应示例：

json

{
  "id": "asset-xyz789",
  "group_id": "group-abc123",
  "asset_type": "image",
  "name": "产品正面图",
  "status": "processing"
}

注意： 素材创建后状态为 processing，需要轮询直到变为 active 才能用于视频生成。

创建视频素材时只需把 asset_type 改为 video：

json

{
  "group_id": "group-abc123",
  "url": "https://example.com/reference.mp4",
  "asset_type": "video",
  "name": "运镜参考视频"
}

4. 上传本地文件

通过 multipart/form-data 上传本地图片或 MP4 视频：

bash

curl -X POST "${API_BASE}/v1/assets/uploads" \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "file=@/path/to/product.png" \
  -F "group_id=group-abc123" \
  -F "asset_type=image" \
  -F "name=产品图片"

表单参数：

字段	类型	必填	说明
`file`	binary	是	图片或 MP4 视频文件，限制见下表
`group_id`	string	是	目标素材分组 ID
`asset_type`	string	是	`image` 或 `video`
`name`	string	否	素材名称；不传则使用文件名

类型	本地上传格式	单文件上限	其他约束
`image`	JPEG、PNG、GIF、WebP、BMP、TIFF	30 MB	单边 300–6000 px，宽高比在 0.4–2.5 之间
`video`	MP4	200 MB	仅接受 MP4 容器；不支持视频 Base64、本地 MOV 或 WebM

本地文件会被保存为最长 24 小时的临时 HTTPS 地址，供 Ark 拉取处理；删除素材或临时地址过期后会被清理。请在素材变为 active 后再用于生成。

5. 查询素材详情

bash

curl "${API_BASE}/v1/assets/asset-xyz789" \
  -H "Authorization: Bearer ${API_KEY}"

响应示例（处理中）：

json

{
  "id": "asset-xyz789",
  "asset_type": "image",
  "name": "产品正面图",
  "status": "processing"
}

响应示例（已就绪）：

json

{
  "id": "asset-xyz789",
  "asset_type": "image",
  "name": "产品正面图",
  "status": "active",
  "reference": "asset://asset-xyz789"
}

素材状态

状态	说明
`processing`	处理中，暂不可用于生成任务
`active`	处理完成，可引用
`failed`	处理失败，请更换 URL 重新创建

6. 在视频生成中使用素材引用

素材变为 active 后，将返回的 reference 放入与素材类型一致的字段。图片素材只能用于 image_url，视频素材只能用于 video_url；类型不匹配、非本人素材或非 active 素材会被拒绝。

bash

curl -X POST "${API_BASE}/v1/video/generations" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Seedance-2.0-overseas-ark-1",
    "content": [
      {
        "type": "text",
        "text": "基于参考图生成一段产品宣传视频"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "asset://asset-xyz789"
        },
        "role": "reference_image"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

视频素材引用示例：

json

{
  "model": "Seedance-2.0-overseas-ark-1",
  "content": [
    {"type": "text", "text": "沿用参考视频的运镜节奏，生成产品宣传片"},
    {
      "type": "video_url",
      "video_url": {"url": "asset://asset-video-xyz789"},
      "role": "reference_video"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}

计费说明： 素材创建、查询和删除不计生成额度。异步视频生成会先预扣额度，并在上游任务成功且返回最终用量后自动进行二次结算；请以完成后的消费记录和任务最终状态为准，不要把预扣额度当作最终费用。

7. 删除素材

bash

curl -X DELETE "${API_BASE}/v1/assets/asset-xyz789" \
  -H "Authorization: Bearer ${API_KEY}"

8. 删除素材分组

删除分组时会同时删除该分组下的所有素材：

bash

curl -X DELETE "${API_BASE}/v1/asset-groups/group-abc123" \
  -H "Authorization: Bearer ${API_KEY}"

完整示例

以下 Python 示例展示完整的素材上传到视频生成流程：

python

import requests
import time

BASE = "https://suanyuan.goesai.com"
HEADERS = {"Authorization": "Bearer sk-your-api-key"}

# 1. 创建分组
group = requests.post(
    f"{BASE}/v1/asset-groups",
    headers=HEADERS,
    json={"name": "产品素材"},
).json()
group_id = group["id"]
print(f"分组已创建: {group_id}")

# 2. 上传素材
asset = requests.post(
    f"{BASE}/v1/assets",
    headers=HEADERS,
    json={
        "group_id": group_id,
        "url": "https://example.com/product.png",
        "asset_type": "image",
        "name": "产品图"
    },
).json()
asset_id = asset["id"]
print(f"素材已创建: {asset_id}, 状态: {asset['status']}")

# 3. 等待素材就绪
for _ in range(30):
    detail = requests.get(
        f"{BASE}/v1/assets/{asset_id}",
        headers=HEADERS,
    ).json()
    if detail["status"] == "active":
        print(f"素材已就绪: {detail['reference']}")
        break
    if detail["status"] == "failed":
        raise RuntimeError("素材处理失败")
    time.sleep(2)

# 4. 使用素材生成视频
task = requests.post(
    f"{BASE}/v1/video/generations",
    headers=HEADERS,
    json={
        "model": "Seedance-2.0-overseas-ark-1",
        "content": [
            {"type": "text", "text": "基于产品图生成宣传视频"},
            {
                "type": "image_url",
                "image_url": {"url": f"asset://{asset_id}"},
                "role": "reference_image",
            },
        ],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
).json()
print(f"视频任务已创建: {task['id']}")

常见问题

Q: 素材 URL 有什么要求？

必须是公网可访问的 HTTPS URL，不支持 HTTP、内网地址、回环/链路本地地址、裸 IP 或非标准端口。建议先用 curl -I -L 确认返回 200；图片应返回图片类型，视频应返回 video/mp4。视频 URL 不得依赖登录、Cookie 或一次性链接。

Q: 素材在 processing 状态会持续多久？

通常几秒到几十秒。建议每 2 秒轮询一次，超过 60 秒仍为 processing 可能说明 URL 不可访问。

Q: 可以上传视频或音频吗？

支持图片（image）和视频（video）。本地视频当前仅支持不超过 200 MB 的 MP4；URL 视频应为可直接下载的 HTTPS MP4。暂不支持音频素材、视频 Base64、本地 MOV 或 WebM。

Q: 为什么已成功的视频任务还会出现一笔后续额度变动？

视频生成是异步计费：提交时只做预扣，任务成功后会依据上游返回的最终用量进行二次结算，可能补扣或退还差额。该过程由平台自动完成；如任务已经完成但较长时间未见最终消费记录，请联系支持并提供任务 ID。

Q: 删除分组会影响已经引用该分组素材的视频任务吗？

不会影响已经完成的视频任务。但正在处理中的任务如果引用了被删除的素材，可能会失败。

素材库 (Asset Library) ​

概念 ​

工作流程 ​

鉴权 ​

接口列表 ​

1. 创建素材分组 ​

2. 列出素材分组 ​

3. 创建素材（URL 方式） ​

4. 上传本地文件 ​

5. 查询素材详情 ​

素材状态 ​

6. 在视频生成中使用素材引用 ​

7. 删除素材 ​

8. 删除素材分组 ​

完整示例 ​

常见问题 ​

素材库 (Asset Library)

概念

工作流程

鉴权

接口列表

1. 创建素材分组

2. 列出素材分组

3. 创建素材（URL 方式）

4. 上传本地文件

5. 查询素材详情

素材状态

6. 在视频生成中使用素材引用

7. 删除素材

8. 删除素材分组

完整示例

常见问题