# 公共数字人形象列表 API Documentation

> 列出平台公共数字人形象及公网 video_url，可直接用于数字人高清合成。支持按性别、关键词筛选。查询不扣费。

## Overview

This document describes how to call the **公共数字人形象列表** API.

- **Model / path slug**: `aihuman/public_avatars`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/53`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/aihuman/public_avatars`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `gender` | No | 可选 female\|male |
| `keyword` | No | 可选，按名称/风格/标签模糊筛选 |
| `id` | No | 可选，精确取某一形象 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
https://apis.xiaobao.ink/api/aihuman/public_avatars?key=你的密钥
```

## Details

## 接口说明：

返回平台维护的**公共数字人形象**列表。每条含公网可访问的 `video_url`，可直接作为 [AI数字人高清合成](/doc/11) 的 `video_url`。无需自备人物视频即可试跑整条链路。查询不扣费。

**请求方法：**支持 `GET` 与 `POST`。

后续可继续在目录中追加新形象；接入方以本接口返回为准。

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/json 或 application/x-www-form-urlencoded（POST 时） |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| gender | 否 | string | female | 按性别筛选：female / male |
| keyword | 否 | string | 新闻 | 按名称、风格、标签模糊筛选；亦可用参数名 q |
| id | 否 | string | news_anchor_female | 精确取某一形象 |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| total | int | 列表条数 |
| list | array | 形象列表 |
| list[].id | string | 形象唯一标识 |
| list[].name | string | 展示名称 |
| list[].gender | string | female / male |
| list[].style | string | 风格简述 |
| list[].video_url | string | 人物参考视频公网地址，可直接传给 create |
| list[].tags | array | 标签 |
| usage | object | 使用提示（create 地址等） |

## Response Example

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "total": 3,
        "list": [
            {
                "id": "news_anchor_female",
                "name": "新闻主播",
                "gender": "female",
                "style": "职业女性·专业",
                "video_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/video/20260921/202609211043306cd031836.mp4",
                "tags": [
                    "新闻",
                    "主播",
                    "商务",
                    "女"
                ],
                "sort": 10
            },
            {
                "id": "daily_natural_female",
                "name": "日常自然",
                "gender": "female",
                "style": "日常·自然",
                "video_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/video/20260921/20260921120938441b78699.mp4",
                "tags": [
                    "日常",
                    "自然",
                    "女"
                ],
                "sort": 20
            },
            {
                "id": "news_anchor_male",
                "name": "男生新闻主播",
                "gender": "male",
                "style": "男性·新闻主播",
                "video_url": "https://wikixiaobao.oss-accelerate.aliyuncs.com/uploads/video/20260921/20260921105256763f36229.mp4",
                "tags": [
                    "新闻",
                    "主播",
                    "男"
                ],
                "sort": 30
            }
        ],
        "usage": {
            "create": "https://apis.xiaobao.ink/api/aihuman/create",
            "hint": "将 list[].video_url 作为 create 接口的 video_url"
        }
    }
}
```

## Error Codes

| HTTP 响应状态码 | 说明 |
| --- | --- |
| 200 | 查询成功 |
| 400 | 接口未开启或未入库 |
| 401 | 认证失败，请检查 key |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._