跳到主要内容
LocoPal AiLocoPal Ai
素材库素材库接口

使用指南

素材

提交图片素材、查询审核状态与查询素材列表

查看 Markdown

素材

素材提交后由平台异步处理，状态从 Processing 变为 Active 后才能用于视频任务。

提交图片素材

POST/api/v1/materials/assets

认证方式

Authorization: Bearer <API_KEY>。

请求体 · application/json

Prop

Type

image_url 与 data_url 只能提交一个。image_url 也可以是 data:image/...;base64,...，平台会把它按内联图片处理。使用远程 URL 时，地址必须是平台可以公开下载的 http(s):// 地址（http 和 https 都支持），并且不依赖 Cookie、Referer、登录页面或浏览器会话，在平台处理期间保持有效。

远程 image_url 会先经过平台的快速中转缓存，再由素材库镜像，普通图片通常可以在秒级完成。平台也支持内联图片：可以把 image_url 的值写成 data:image/...;base64,...，或使用单独的 data_url 字段。对于已经在客户端本地的图片，内联提交可以进一步减少一次外部下载。

data_url 会把整张图以 base64 上传（体积约为原图的 1.33 倍），只在图片确实无法提供公网地址时使用：例如图片在需要登录的地址后面、在内网、或只有本地文件。使用 data_url 时上传耗时取决于图片大小和调用方带宽，平台会将图片写入短期临时中转，而不是永久平台素材存储。素材库完成镜像并进入 Active 后，预览优先使用素材库返回的 preview_url，临时文件由中转服务自动清理。

图片素材只能提交到 virtual 分组；real 分组的素材由真人扫码授权流程产生。

request_id 也可以通过 Idempotency-Key 请求头提交。相同账号使用同一个 request_id 重复提交时，平台会返回第一次创建成功的同一个素材，不会再次创建上游素材。未提交 request_id 时，平台会按账号、分组、标题和原始图片载荷自动生成稳定值；同一图片和标题的重试仍然可以安全复用。

请求示例

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "$LOCOPAL_IMAGE_URL",
  "tags": ["人物", "正面"]
}
JSON

使用本地图片时改为提交 data_url：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "file_name": "person.png",
  "data_url": "data:image/png;base64,iVBORw0KGgo..."
}

如果客户端希望继续使用 image_url 字段，也可以直接提交内联图片：

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "data:image/png;base64,iVBORw0KGgo..."
}

响应参数

参数类型说明
codeinteger成功时为 0
msgstring成功时为 图片素材已提交
data.asset_idstring素材 ID，等于 data.asset.id
data.asset.idstring素材 ID，视频任务用 asset://<id> 引用
data.asset.kindstring素材类型，图片为 image
data.asset.titlestring素材名称（自动补全后的最终值）
data.asset.request_idstring / null本次上传使用的幂等请求 ID
data.asset.platform_asset_idstring素材服务的平台素材 ID，用于排查；当前部署通常与 id 相同
data.asset.group_idstring所属分组 ID
data.asset.statusstring受理后为 Processing
data.asset.error_messagestring / null处理失败原因，正常为 null
data.asset.notestring / null备注，未提交时为 null
data.asset.tagsstring[]标签列表，未提交时通常为空数组
data.asset.mime_typestring / null素材服务返回的 MIME 类型，未返回时为 null
data.asset.bytesinteger / null素材文件大小，素材服务未返回时为 null
data.asset.created_atinteger创建时间（Unix 秒）
data.asset.updated_atinteger更新时间（Unix 秒）

响应体

{
  "code": 0,
  "data": {
    "asset_id": "asset-20260911035115-etexu",
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Processing",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069876
    }
  },
  "msg": "图片素材已提交"
}

提交成功只表示素材已受理，提交视频任务前仍要查询状态。

错误响应

HTTPmsg说明
400缺少 group_id未提供分组
400image_url 必须是可公开下载的 http(s) 地址，当前为 …地址协议不是 http / https，或地址不完整；改用公网 http(s) 地址，或改用 data_url
400image_url 与 data_url 只能提交一个两个字段同时提交或都未提交
400data_url 必须是 data:image/...;base64,... 格式data_url 格式错误
400图片数据无效或超过 20MB图片数据为空或超过 20 MB
400素材名称不能为空 / 素材名称不能超过 64 个字符title 校验失败
401Invalid tokenAPI Key 缺失、错误或已失效
404素材分组不存在或不属于当前账号group_id 错误或不属于当前账号
404素材分组不存在或不是虚拟素材分组向 real 分组提交图片
502 / 503素材服务暂不可用素材服务异常，保留请求信息后重试

查询单个素材

GET/api/v1/materials/assets/{asset_id}

认证方式

Authorization: Bearer <API_KEY>。

请求参数 · path

Prop

Type

请求示例

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-20260911035115-etexu" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

响应参数

参数类型说明
codeinteger成功时为 0
msgstring成功时为 OK
data.assetobject素材对象，字段同提交接口

data.asset.status 的取值与处理方式：

状态含义程序行为
Processing素材仍在处理或审核保存 asset_id，稍后查询，不要重复提交
Active素材可用于支持该素材类型的任务在视频 content 中使用 asset://<asset_id>
Failed素材处理失败读取 error_message，修正源图片后创建新的素材

响应体

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Active",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069877
    }
  },
  "msg": "OK"
}

审核失败同样返回 HTTP 200，失败原因在 error_message：

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "status": "Failed",
      "error_message": "素材处理失败"
    }
  },
  "msg": "OK"
}

错误响应

HTTPmsg说明
401Invalid tokenAPI Key 缺失、错误或已失效
404素材不存在或无权访问素材 ID 错误、已删除或不属于当前账号
502 / 503素材服务暂不可用素材服务异常，保留请求信息后重试

查询素材列表

GET/api/v1/materials/assets

认证方式

Authorization: Bearer <API_KEY>。

请求参数 · query

参数类型必填默认说明
pageinteger否1页码
page_sizeinteger否20每页条数，最大 100
group_idstring否—只返回该分组下的素材

请求示例

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets?page=1&page_size=20&group_id=group-1789069780-5762d1" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

响应参数

参数类型说明
codeinteger成功时为 0
msgstring成功时为 OK
data.totalinteger符合条件的素材总数
data.page / data.page_sizeinteger本次分页参数
data.assetsarray素材列表，字段同提交接口

响应体

{
  "code": 0,
  "data": {
    "assets": [
      {
        "id": "asset-20260911035115-etexu",
        "platform_asset_id": "asset-20260911035115-etexu",
        "kind": "image",
        "title": "角色正面定妆图",
        "group_id": "group-1789069780-5762d1",
        "status": "Active",
        "error_message": null,
        "note": null,
        "tags": [],
        "mime_type": null,
        "bytes": null,
        "created_at": 1789069876,
        "updated_at": 1789069877
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

错误响应

HTTPmsg说明
401Invalid tokenAPI Key 缺失、错误或已失效
404素材分组不存在或无权访问指定的 group_id 不存在或不属于当前账号
500 / 502 / 503素材服务暂不可用素材服务异常，保留请求信息后重试
这一页有帮助吗？

素材分组

创建与查询素材分组的接口说明

同步素材状态

按当前账号刷新分组与素材的名称、状态、错误信息和访问地址

本页目录

素材提交图片素材认证方式请求体 · application/json请求示例响应参数响应体错误响应查询单个素材认证方式请求参数 · path请求示例响应参数响应体错误响应查询素材列表认证方式请求参数 · query请求示例响应参数响应体错误响应