上传素材 ​

上传图片、视频、音频素材，用于视频生成任务。

重要：素材会不定期删除，请勿将素材接口作为长期存储服务。请保留原始文件，并在素材失效后重新上传。

接口信息 ​

接口：POST https://api-ai.xku.com/ark/v1/assets

请求参数 ​

字段类型是否必填说明
URLstring是素材的公网可访问地址；仅支持 URL，不支持 Base64
Namestring否素材名称，最多 64 个字符；仅用于素材列表模糊搜索，不会传入模型推理
AssetTypestring是素材类型：Image、Video 或 Audio
ProjectNamestring否资源所属项目名称，默认 default

素材要求 ​

素材类型格式时长尺寸与大小
图片jpeg、png、webp、bmp、tiff、gif、heic、heif-宽高比 (0.4, 2.5)；宽高 (300, 6000) px；单张小于 30 MB
视频mp4、mov[2, 15] 秒480p、720p、1080p；宽高比 [0.4, 2.5]；宽高 [300, 6000] px；总像素数 [409600, 2086876]；不超过 200 MB；帧率 [24, 60] FPS
音频wav、mp3[2, 15] 秒不超过 15 MB

使用示例 ​

上传图片素材 ​

bash
curl -X POST https://api-ai.xku.com/ark/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/image.jpg",
    "Name": "测试图片",
    "AssetType": "Image",
    "ProjectName": "default"
  }'

上传视频素材 ​

bash
curl -X POST https://api-ai.xku.com/ark/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/video.mp4",
    "Name": "测试视频",
    "AssetType": "Video",
    "ProjectName": "default"
  }'

上传音频素材 ​

bash
curl -X POST https://api-ai.xku.com/ark/v1/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "URL": "https://example.com/audio.mp3",
    "Name": "测试音频",
    "AssetType": "Audio",
    "ProjectName": "default"
  }'

响应参数 ​

字段类型说明
Idstring素材 ID

响应示例 ​

json
{
    "Id": "asset-20250101000000-0000"
}

后续步骤 ​

素材创建后会进行异步审核。创建成功后需要调用查询素材接口，直到 Status 进入终态（Active 或 Failed）。

审核通过后，即可在视频生成任务中使用素材 ID，格式为 asset:// + 素材 ID，例如：asset://asset-20250101000000-0000。

注意事项 ​

  1. 素材会不定期删除，请勿将素材接口作为长期存储服务
  2. 仅支持通过 URL 上传素材，不支持 Base64 编码
  3. 素材 URL 需要是公网可访问的地址
  4. 素材审核需要时间，请耐心等待
  5. 建议使用稳定的对象存储服务存放素材源文件