Chuyển đến nội dung chính
LocoPal AiLocoPal Ai
Thư viện tư liệuAPI thư viện tư liệu

Hướng dẫn

Tư liệu

Gửi tư liệu hình ảnh, truy vấn trạng thái kiểm duyệt và truy vấn danh sách tư liệu

Xem Markdown

Tư liệu

Sau khi gửi, tư liệu được nền tảng xử lý bất đồng bộ; chỉ sau khi trạng thái chuyển từ Processing thành Active mới dùng được cho tác vụ video.

Gửi tư liệu hình ảnh

POST/api/v1/materials/assets

Cách xác thực

Authorization: Bearer <API_KEY>.

Phần thân yêu cầu · application/json

Prop

Type

image_url và data_url chỉ được gửi một cái. image_url cũng có thể là data:image/...;base64,..., nền tảng sẽ xử lý nó như ảnh nội tuyến. Khi dùng URL từ xa, địa chỉ phải là địa chỉ http(s):// mà nền tảng có thể tải công khai (http và https đều hỗ trợ), không phụ thuộc Cookie, Referer, trang đăng nhập hoặc phiên trình duyệt, và giữ hiệu lực trong thời gian nền tảng xử lý.

image_url từ xa sẽ đi qua bộ nhớ đệm trung chuyển nhanh của nền tảng trước, rồi được thư viện tư liệu sao chép; hình ảnh thông thường thường có thể hoàn tất trong vài giây. Nền tảng cũng hỗ trợ ảnh nội tuyến: có thể viết giá trị image_url thành data:image/...;base64,..., hoặc dùng trường data_url riêng. Với hình ảnh đã có sẵn ở phía máy khách, gửi nội tuyến có thể giảm thêm một lần tải xuống bên ngoài.

data_url sẽ tải toàn bộ ảnh dưới dạng base64 (kích thước khoảng 1,33 lần ảnh gốc), chỉ dùng khi hình ảnh thực sự không thể cung cấp địa chỉ công khai: ví dụ ảnh nằm sau địa chỉ cần đăng nhập, trong mạng nội bộ hoặc chỉ có tệp cục bộ. Khi dùng data_url, thời gian tải lên phụ thuộc vào kích thước ảnh và băng thông của bên gọi; nền tảng sẽ ghi ảnh vào trung chuyển tạm thời ngắn hạn chứ không phải kho tư liệu vĩnh viễn của nền tảng. Sau khi thư viện tư liệu sao chép xong và chuyển vào Active, bản xem trước ưu tiên dùng preview_url do thư viện tư liệu trả về, tệp tạm thời được dịch vụ trung chuyển tự động dọn dẹp.

Tư liệu hình ảnh chỉ được gửi vào nhóm virtual; tư liệu của nhóm real được tạo bởi quy trình ủy quyền quét mã người thật.

request_id cũng có thể được gửi qua tiêu đề yêu cầu Idempotency-Key. Khi cùng một tài khoản gửi lặp lại với cùng request_id, nền tảng sẽ trả về cùng một tư liệu đã tạo thành công lần đầu, không tạo lại tư liệu thượng nguồn. Khi không gửi request_id, nền tảng sẽ tự động tạo giá trị ổn định theo tài khoản, nhóm, tiêu đề và dữ liệu ảnh gốc; thử lại cùng một ảnh và tiêu đề vẫn có thể tái sử dụng an toàn.

Ví dụ yêu cầu

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

Khi dùng ảnh cục bộ, đổi sang gửi 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..."
}

Nếu máy khách muốn tiếp tục dùng trường image_url, cũng có thể gửi trực tiếp ảnh nội tuyến:

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

Tham số phản hồi

Tham sốKiểuMô tả
codeintegerKhi thành công là 0
msgstringKhi thành công là 图片素材已提交
data.asset_idstringID tư liệu, bằng data.asset.id
data.asset.idstringID tư liệu, tác vụ video dùng asset://<id> để tham chiếu
data.asset.kindstringLoại tư liệu, hình ảnh là image
data.asset.titlestringTên tư liệu (giá trị cuối cùng sau khi tự động điền)
data.asset.request_idstring / nullID yêu cầu idempotent dùng cho lần tải lên này
data.asset.platform_asset_idstringID tư liệu nền tảng của dịch vụ tư liệu, dùng để khắc phục sự cố; triển khai hiện tại thường giống id
data.asset.group_idstringID nhóm chứa tư liệu
data.asset.statusstringSau khi được tiếp nhận là Processing
data.asset.error_messagestring / nullNguyên nhân xử lý thất bại, bình thường là null
data.asset.notestring / nullGhi chú, khi chưa gửi là null
data.asset.tagsstring[]Danh sách nhãn, khi chưa gửi thường là mảng rỗng
data.asset.mime_typestring / nullKiểu MIME do dịch vụ tư liệu trả về, khi không trả về là null
data.asset.bytesinteger / nullKích thước tệp tư liệu, khi dịch vụ tư liệu không trả về là null
data.asset.created_atintegerThời gian tạo (giây Unix)
data.asset.updated_atintegerThời gian cập nhật (giây Unix)

Nội dung phản hồi

{
  "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": "图片素材已提交"
}

Gửi thành công chỉ có nghĩa là tư liệu đã được tiếp nhận; trước khi gửi tác vụ video vẫn phải truy vấn trạng thái.

Phản hồi lỗi

HTTPmsgMô tả
400缺少 group_idChưa cung cấp nhóm
400image_url 必须是可公开下载的 http(s) 地址，当前为 …Giao thức địa chỉ không phải http / https, hoặc địa chỉ không đầy đủ; đổi sang địa chỉ http(s) công khai, hoặc dùng data_url
400image_url 与 data_url 只能提交一个Gửi đồng thời cả hai trường hoặc không gửi trường nào
400data_url 必须是 data:image/...;base64,... 格式Định dạng data_url sai
400图片数据无效或超过 20MBDữ liệu ảnh trống hoặc vượt quá 20 MB
400素材名称不能为空 / 素材名称不能超过 64 个字符Kiểm tra title thất bại
401Invalid tokenKhóa API thiếu, sai hoặc đã hết hiệu lực
404素材分组不存在或不属于当前账号group_id sai hoặc không thuộc tài khoản hiện tại
404素材分组不存在或不是虚拟素材分组Gửi hình ảnh vào nhóm real
502 / 503素材服务暂不可用Dịch vụ tư liệu bất thường, giữ thông tin yêu cầu rồi thử lại

Truy vấn một tư liệu

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

Cách xác thực

Authorization: Bearer <API_KEY>.

Tham số yêu cầu · path

Prop

Type

Ví dụ yêu cầu

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

Tham số phản hồi

Tham sốKiểuMô tả
codeintegerKhi thành công là 0
msgstringKhi thành công là OK
data.assetobjectĐối tượng tư liệu, trường giống API gửi

Giá trị và cách xử lý của data.asset.status:

Trạng tháiÝ nghĩaHành vi chương trình
ProcessingTư liệu vẫn đang xử lý hoặc kiểm duyệtLưu asset_id, truy vấn sau, không gửi lặp lại
ActiveTư liệu có thể dùng cho tác vụ hỗ trợ loại tư liệu nàyDùng asset://<asset_id> trong content của video
FailedXử lý tư liệu thất bạiĐọc error_message, sửa ảnh nguồn rồi tạo tư liệu mới

Nội dung phản hồi

{
  "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"
}

Kiểm duyệt thất bại cũng trả về HTTP 200, nguyên nhân thất bại ở error_message:

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

Phản hồi lỗi

HTTPmsgMô tả
401Invalid tokenKhóa API thiếu, sai hoặc đã hết hiệu lực
404素材不存在或无权访问ID tư liệu sai, đã xóa hoặc không thuộc tài khoản hiện tại
502 / 503素材服务暂不可用Dịch vụ tư liệu bất thường, giữ thông tin yêu cầu rồi thử lại

Truy vấn danh sách tư liệu

GET/api/v1/materials/assets

Cách xác thực

Authorization: Bearer <API_KEY>.

Tham số yêu cầu · query

Tham sốKiểuBắt buộcMặc địnhMô tả
pageintegerKhông1Số trang
page_sizeintegerKhông20Số mục mỗi trang, tối đa 100
group_idstringKhông—Chỉ trả về tư liệu trong nhóm này

Ví dụ yêu cầu

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

Tham số phản hồi

Tham sốKiểuMô tả
codeintegerKhi thành công là 0
msgstringKhi thành công là OK
data.totalintegerTổng số tư liệu phù hợp
data.page / data.page_sizeintegerTham số phân trang lần này
data.assetsarrayDanh sách tư liệu, trường giống API gửi

Nội dung phản hồi

{
  "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"
}

Phản hồi lỗi

HTTPmsgMô tả
401Invalid tokenKhóa API thiếu, sai hoặc đã hết hiệu lực
404素材分组不存在或无权访问group_id chỉ định không tồn tại hoặc không thuộc tài khoản hiện tại
500 / 502 / 503素材服务暂不可用Dịch vụ tư liệu bất thường, giữ thông tin yêu cầu rồi thử lại
Trang này có hữu ích không?

Nhóm tư liệu

Mô tả API tạo và truy vấn nhóm tư liệu

Đồng bộ trạng thái tư liệu

Làm mới tên, trạng thái, thông tin lỗi và địa chỉ truy cập của nhóm và tư liệu theo tài khoản hiện tại

Trong trang này

Tư liệuGửi tư liệu hình ảnhCách xác thựcPhần thân yêu cầu · application/jsonVí dụ yêu cầuTham số phản hồiNội dung phản hồiPhản hồi lỗiTruy vấn một tư liệuCách xác thựcTham số yêu cầu · pathVí dụ yêu cầuTham số phản hồiNội dung phản hồiPhản hồi lỗiTruy vấn danh sách tư liệuCách xác thựcTham số yêu cầu · queryVí dụ yêu cầuTham số phản hồiNội dung phản hồiPhản hồi lỗi