Nhân vật

Danh sách nhân vật

Danh sách nhân vật của bạn, mới sửa trước. Không tốn credit.

GEThttps://api.sangtao.ai/v2/characters

Xác thực

X-Api-Keystring · headerbắt buộc
API key của bạn, tạo ở trang API key trong tài khoản.

Nhân vật là hồ sơ dùng lại được khi tạo video, để một nhân vật giữ cùng ngoại hình qua nhiều cảnh và nhiều video. Một hồ sơ gồm tên, mô tả ngoại hình, tiểu sử, tên gọi khác, và tối đa 3 ảnh tham chiếu. Dùng ở characterIds của Motion compose và Video Studio.

Các API nhân vật không tốn credit.

Tham số query

pageint
Số trang, từ 1. Bỏ trống cả page lẫn pageSize thì nhận hết.
pageSizeint
Số mục mỗi trang. Mặc định 50, tối đa 200. Gửi limit cũng được, cùng nghĩa.

Tổng số, tính mọi trang, nằm ở header X-Total-Count.

Response

Một mảng Character, mới sửa trước. Mỗi Character gồm:

idstringbắt buộc
Mã nhân vật ch_…. Dùng ở characterIds khi tạo video
namestringbắt buộc
Tên, bắt buộc, tối đa 100 ký tự
appearanceDescriptionstring | null
Mô tả ngoại hình để AI vẽ đúng, tối đa 1.000 ký tự. Nên viết tiếng Anh, ngắn, liệt kê đặc điểm
biographystring | null
Tiểu sử hoặc tính cách, giúp AI xếp nhân vật vào đúng cảnh. Tối đa 2.000 ký tự
aliasesstring | null
Tên gọi khác, ngăn cách bằng dấu phẩy, tối đa 200 ký tự. Giúp AI nhận ra nhân vật khi truyện gọi bằng tên khác
publishStatusstring | null
Trạng thái chia sẻ cộng đồng
Giá trị có thể:nullpendingapprovedrejected
createdAtstringbắt buộc
Thời điểm tạo (ISO 8601, UTC)
updatedAtstringbắt buộc
Thời điểm sửa gần nhất (ISO 8601, UTC)
refImagesobject[]bắt buộc
Tối đa 3 ảnh tham chiếu, theo thứ tự sortOrder
Hiện thuộc tính conẨn thuộc tính con
- idstringbắt buộc
  Mã ảnh ci_… — là imageId của Xoá ảnh tham chiếu
- imageUrlstringbắt buộc
  URL của ảnh
- thumbnailUrlstring | null
  URL bản thu nhỏ. Có thể là null vài giây sau khi thêm
- sortOrdernumberbắt buộc
  Thứ tự trong các ảnh của nhân vật

Nhân vật dùng được khi tạo video nếu có ít nhất một trong hai: ảnh tham chiếu hoặc appearanceDescription.

Dùng nhân vật khi tạo video

Truyền mã vào characterIds, tối đa 5 nhân vật cho Motion.

Mã sai định dạng thì nhận 400. Mã của nhân vật không phải của bạn thì nhận 404 CHARACTER_NOT_FOUND (Motion) hoặc bị bỏ qua (Video Studio).

GET/characters

curl "https://api.sangtao.ai/v2/characters" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "ch_3kT9qPz0B",
      "name": "Mèo Mướp",
      "appearanceDescription": "orange tabby cat, chubby body, half-closed drowsy eyes, white belly patch",
      "biography": "Chú mèo lười của tiệm sách, hay ngủ trên quầy thu ngân.",
      "aliases": "Mướp, Bé Mướp",
      "publishStatus": null,
      "createdAt": "2026-11-08T09:12:44Z",
      "updatedAt": "2026-11-08T09:20:01Z",
      "refImages": [
        {
          "id": "ci_8hQ2mZr4K",
          "imageUrl": "https://…/a.png",
          "thumbnailUrl": "https://…/a_thumb.webp",
          "sortOrder": 0
        }
      ]
    }
  ]
}

GET/characters

curl "https://api.sangtao.ai/v2/characters" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "ch_3kT9qPz0B",
      "name": "Mèo Mướp",
      "appearanceDescription": "orange tabby cat, chubby body, half-closed drowsy eyes, white belly patch",
      "biography": "Chú mèo lười của tiệm sách, hay ngủ trên quầy thu ngân.",
      "aliases": "Mướp, Bé Mướp",
      "publishStatus": null,
      "createdAt": "2026-11-08T09:12:44Z",
      "updatedAt": "2026-11-08T09:20:01Z",
      "refImages": [
        {
          "id": "ci_8hQ2mZr4K",
          "imageUrl": "https://…/a.png",
          "thumbnailUrl": "https://…/a_thumb.webp",
          "sortOrder": 0
        }
      ]
    }
  ]
}

Trang trướcDung lượng đã dùng Trang sauLấy một nhân vật