主题

素材库 (Asset Library) ​

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

概念 ​

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

工作流程 ​

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

鉴权 ​

所有素材接口使用与其他 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": "产品宣传视频参考图"
  }'

请求参数：

字段类型必填说明
namestring是分组名称，最长 64 字符
descriptionstring否分组描述
group_typestring否默认 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 方式） ​

将一张公网可访问的图片注册为素材：

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_idstring是目标素材分组 ID
urlstring是素材公网 HTTPS URL
asset_typestring是当前仅支持 image
namestring否素材显示名称

响应示例：

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

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

4. 上传本地文件 ​

通过 multipart/form-data 上传本地图片：

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=产品图片"

表单参数：

字段类型必填说明
filebinary是图片文件，最大 30 MB
group_idstring是目标素材分组 ID
asset_typestring是当前仅支持 image
namestring否素材名称；不传则使用文件名

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：

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

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 确认返回 200 且 Content-Type 为图片类型。

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

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

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

当前仅支持图片类型（image）。视频和音频支持将在后续版本开放。

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

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

GoesAI API 中继平台

Copyright © GoesAI