Tổng quan API thư viện tư liệu

API thư viện tư liệu dùng để tạo nhóm tư liệu, gửi hình ảnh, truy vấn trạng thái tư liệu, đồng bộ tư liệu và khởi tạo ủy quyền quét mã cho người thật. Tất cả API đều dùng cùng một khóa API nền tảng, không cần chữ ký bổ sung và không cần gọi dịch vụ khác.

Quy ước chung (địa chỉ cơ sở, cách xác thực, giới hạn tần suất, tính idempotent) xem Xác thực và quy chuẩn cơ bản.

Các API cụ thể:

Danh sách API

Cấu trúc phản hồi thống nhất

Thành công:

{ "code": 0, "data": {}, "msg": "OK" }

Khi thất bại, mã trạng thái HTTP trùng với code, data là null:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

Cấu trúc thực tế của data

data là đối tượng chứ không phải mảng, các trường cụ thể tùy thuộc vào API. Tập hợp của API danh sách nằm dưới khóa có tên:

{
  "code": 0,
  "data": {
    "groups": [
      { "id": "group-1789069780-5762d1", "name": "我的角色素材", "type": "virtual" }
    ],
    "page": 1,
    "page_size": 20,
    "total": 4
  },
  "msg": "OK"
}

Đừng giả định data trực tiếp là mảng. Danh sách nhóm ở data.groups, danh sách tư liệu ở data.assets. Khi đọc tập hợp hãy đi qua khóa có tên, và dùng data.total để xác định còn trang tiếp theo hay không.

Lưu ý: tài nguyên tự động đăng ký có thể không có id

Nhóm tư liệu do nền tảng tự động đăng ký, id và platform_group_id có thể là chuỗi rỗng:

{ "id": "", "platform_group_id": "", "name": "自动登记素材", "type": "virtual" }

Đừng dùng id làm khóa duy nhất để lưu trữ hoặc hợp nhất kết quả danh sách, nếu không nhiều mục tự động đăng ký sẽ ghi đè lẫn nhau. Nên dùng tổ hợp platform_group_id || id || name, hoặc bỏ qua trực tiếp các mục không thể dùng cho lời gọi API tiếp theo. Ngoại lệ duy nhất là lỗi xác thực: khi khóa API thiếu, sai hoặc đã hết hiệu lực sẽ trả về HTTP 401, nội dung phản hồi là {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}.

Chuẩn bị biến

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/person.png"

Giải thích về ID tư liệu

data.asset_id mà API trả về (bằng data.asset.id) chính là ID duy nhất của tư liệu. ID tư liệu hiển thị trong danh sách「Quản lý tư liệu」của bảng điều khiển cũng là cùng một giá trị, hai nơi có thể dùng thay thế cho nhau, không cần ánh xạ trong chương trình.

Tư liệu thuộc về tài khoản chứ không phải một khóa API cụ thể. Trong cùng một tài khoản, đổi Key, tạo lại Key hoặc chuyển nhóm gọi đều có thể tiếp tục truy vấn và sử dụng tư liệu cũ; tài khoản khác không thấy và cũng không thể tham chiếu.

Mô hình và thư viện tư liệu

Tư liệu được thư viện tư liệu thống nhất của nền tảng lưu trữ: nhập một lần, các mô hình dưới đây đều dùng trực tiếp cùng một tư liệu, không cần chuẩn bị bản sao riêng cho mô hình nào, cũng không cần gửi kiểm duyệt lại.

Vì vậy:

• Tư liệu chỉ nhập một lần, khi đổi mô hình chỉ cần đổi trường model trong yêu cầu, ID tư liệu không cần thay đổi;
• Không cần tạo nhóm riêng cho từng mô hình, cũng không cần chỉ định「đưa tư liệu vào thư viện nào」;
• Tư liệu người thật được thư viện tư liệu hỗ trợ ủy quyền sinh trắc học lưu trữ, các mô hình hỗ trợ tham chiếu là doubao-seedance-2.0-D, doubao-seedance-2.0-D-fast, doubao-seedance-2.0-D-mini, doubao-seedance-2.5-D, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5; gửi tư liệu người thật tới mô hình khác sẽ trả về lỗi có thể đọc được, không được đổi thành URL ảnh thông thường để vượt qua giới hạn.

Sau khi trạng thái tư liệu chuyển thành Active, có thể dùng trong bất kỳ mô hình nào hỗ trợ tham chiếu tư liệu, không cần đợi phía mô hình chuẩn bị lại.

Tư liệu tồn kho trước đây sẽ được nền tảng chuẩn bị một lần khi lần đầu được một mô hình tham chiếu; sau khi chuẩn bị xong, hành vi giống như tư liệu được tham chiếu trực tiếp; tư liệu mới nhập không cần bước này.