> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialvision.tisyk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 私域人像 Avatar 接口参考

> 私域人像写真、姿态替换与数字人接口

## ⑩  删除素材

`DELETE /v1/private-avatar/assets/{id}`

删除指定虚拟人像素材。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  AssetId
</ParamField>

<ParamField query="model" type="string" required>
  路由模型（必填）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X DELETE "https://socialvision.tisyk.xyz/v1/private-avatar/assets/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {}
}
```

***

## ⑤  删除素材组

`DELETE /v1/private-avatar/groups/{id}`

删除指定虚拟人像素材组。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  GroupId
</ParamField>

<ParamField query="model" type="string" required>
  路由模型（必填）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X DELETE "https://socialvision.tisyk.xyz/v1/private-avatar/groups/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {}
}
```

***

## ⑧  查询素材状态

`GET /v1/private-avatar/assets/{id}`

查询单个素材的状态与详情；Processing 状态需轮询直至 Active 或 Failed。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  AssetId（接口⑥ Result.Id）
</ParamField>

<ParamField query="model" type="string" required>
  路由模型（必填）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/v1/private-avatar/assets/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "AssetType": "Image",
    "CreateTime": "string",
    "GroupId": "string",
    "Id": "string",
    "Name": "string",
    "Status": "Processing",
    "URL": "string",
    "UpdateTime": "string"
  }
}
```

***

## ③  查询单个素材组

`GET /v1/private-avatar/groups/{id}`

根据 GroupId 查询单个虚拟人像素材组详情。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  GroupId
</ParamField>

<ParamField query="model" type="string" required>
  路由模型（必填）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl "https://socialvision.tisyk.xyz/v1/private-avatar/groups/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "CreateTime": "string",
    "Description": "string",
    "GroupType": "AIGC",
    "Id": "string",
    "Name": "string",
    "UpdateTime": "string"
  }
}
```

***

## ⑨  更新素材

`PATCH /v1/private-avatar/assets/{id}`

更新素材备注名等元信息。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  AssetId
</ParamField>

### 请求体参数 (Body)

<ParamField body="Id" type="string" required>
  与路径 id 一致
</ParamField>

<ParamField body="Name" type="string">
  名称
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X PATCH "https://socialvision.tisyk.xyz/v1/private-avatar/assets/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {}
}
```

***

## ④  更新素材组

`PATCH /v1/private-avatar/groups/{id}`

更新素材组名称、描述等元信息。

### 请求参数 (Query / Path)

<ParamField path="id" type="string" required>
  GroupId
</ParamField>

### 请求体参数 (Body)

<ParamField body="Description" type="string">
  描述
</ParamField>

<ParamField body="Id" type="string" required>
  与路径 id 一致
</ParamField>

<ParamField body="Name" type="string">
  名称
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "Description": "updated",
  "Id": "group-20260601191715-9q47m",
  "Name": "renamed_group",
  "model": "doubao-seedance-2-0-260128"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X PATCH "https://socialvision.tisyk.xyz/v1/private-avatar/groups/{id}" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Description": "updated",
  "Id": "group-20260601191715-9q47m",
  "Name": "renamed_group",
  "model": "doubao-seedance-2-0-260128"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {}
}
```

***

## ⑦  查询素材列表

`POST /v1/private-avatar/assets/list`

分页查询素材列表，支持按素材组、状态、名称筛选。

### 请求体参数 (Body)

<ParamField body="Filter" type="object">
  过滤条件
</ParamField>

<ParamField body="PageNumber" type="integer">
  页码
</ParamField>

<ParamField body="PageSize" type="integer">
  每页条数
</ParamField>

<ParamField body="SortBy" type="string">
  排序字段
</ParamField>

<ParamField body="SortOrder" type="string">
  排序方向（asc / desc）
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "Filter": {
    "GroupIds": [
      "group-20260601191715-9q47m"
    ],
    "GroupType": "AIGC",
    "Name": "雀国华",
    "Statuses": [
      "Active",
      "Processing"
    ]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "GroupId",
  "SortOrder": "Asc",
  "model": "doubao-seedance-2-0-260128"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/private-avatar/assets/list" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Filter": {
    "GroupIds": [
      "group-20260601191715-9q47m"
    ],
    "GroupType": "AIGC",
    "Name": "雀国华",
    "Statuses": [
      "Active",
      "Processing"
    ]
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "GroupId",
  "SortOrder": "Asc",
  "model": "doubao-seedance-2-0-260128"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "Items": [
      {
        "AssetType": "Image",
        "CreateTime": "string",
        "GroupId": "string",
        "Id": "string",
        "Name": "string",
        "Status": "Processing",
        "URL": "string",
        "UpdateTime": "string"
      }
    ],
    "PageNumber": 0,
    "PageSize": 0,
    "Total": 0
  }
}
```

***

## ⑥  上传素材

`POST /v1/private-avatar/assets`

上传素材 URL 到素材组，返回 AssetId；素材处于 Processing 时需轮询接口⑧。

### 请求体参数 (Body)

<ParamField body="AssetType" type="string" required>
  首字母大写
</ParamField>

<ParamField body="GroupId" type="string" required>
  接口①返回的 Result.Id
</ParamField>

<ParamField body="Name" type="string">
  素材备注名（可选）
</ParamField>

<ParamField body="URL" type="string" required>
  素材公网可访问地址（字段名全大写 URL）
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "AssetType": "Image",
  "GroupId": "184834733006389276",
  "Name": "full-body",
  "URL": "https://example.com/figure.jpg",
  "model": "doubao-seedance-2-0-260128"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/private-avatar/assets" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "AssetType": "Image",
  "GroupId": "184834733006389276",
  "Name": "full-body",
  "URL": "https://example.com/figure.jpg",
  "model": "doubao-seedance-2-0-260128"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "Id": "string"
  }
}
```

***

## ②  查询素材组列表

`POST /v1/private-avatar/groups/list`

分页查询素材组列表，支持按名称、GroupIds、GroupType 筛选。

### 请求体参数 (Body)

<ParamField body="Filter" type="object">
  过滤条件
</ParamField>

<ParamField body="PageNumber" type="integer">
  页码
</ParamField>

<ParamField body="PageSize" type="integer">
  每页条数
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "Filter": {
    "GroupIds": [
      "group-20260601191715-9q47m"
    ],
    "GroupType": "AIGC",
    "Name": "暴建军"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "model": "doubao-seedance-2-0-260128"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/private-avatar/groups/list" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Filter": {
    "GroupIds": [
      "group-20260601191715-9q47m"
    ],
    "GroupType": "AIGC",
    "Name": "暴建军"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "model": "doubao-seedance-2-0-260128"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "Items": [
      {
        "CreateTime": "string",
        "Description": "string",
        "GroupType": "AIGC",
        "Id": "string",
        "Name": "string",
        "UpdateTime": "string"
      }
    ],
    "PageNumber": 0,
    "PageSize": 0,
    "Total": 0
  }
}
```

***

## ①  创建素材组

`POST /v1/private-avatar/groups`

创建虚拟人像素材组，返回 GroupId 供后续素材上传使用。

### 请求体参数 (Body)

<ParamField body="Description" type="string">
  素材组描述（可选）
</ParamField>

<ParamField body="GroupType" type="string">
  虚拟人像固定 AIGC，可省略
</ParamField>

<ParamField body="Name" type="string" required>
  素材组名称（必填）
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (JSON)

```json theme={null}
{
  "Description": "可选描述",
  "GroupType": "AIGC",
  "Name": "my_virtual_group",
  "model": "doubao-seedance-2-0-260128"
}
```

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/private-avatar/groups" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "Description": "可选描述",
  "GroupType": "AIGC",
  "Name": "my_virtual_group",
  "model": "doubao-seedance-2-0-260128"
}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "Id": "string"
  }
}
```

***

## ⑪  生成真人认证链接

`POST /v1/real-avatar/auth/session`

生成真人 H5 认证链接，返回 BytedToken 与 H5Link 供演员完成认证。

### 请求体参数 (Body)

<ParamField body="CallbackURL" type="string" required>
  演员认证完成后浏览器跳转地址（业务方自己的前端页面，必填）
</ParamField>

<ParamField body="Lng" type="string">
  H5 页面语言（可选）
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/real-avatar/auth/session" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "BytedToken": "string",
    "CallbackURL": "string",
    "H5Link": "string"
  }
}
```

***

## ⑫  BytedToken 换取 GroupId

`POST /v1/real-avatar/groups/from-token`

用接口⑪返回的 BytedToken 换取真人素材 GroupId（须在 120 秒内调用）。

### 请求体参数 (Body)

<ParamField body="BytedToken" type="string" required>
  接口⑪ Result.BytedToken（须在 120 秒内调用）
</ParamField>

<ParamField body="model" type="string" required>
  路由选择参数（固定传此值）
</ParamField>

### 请求示例 (cURL)

```bash theme={null}
curl -X POST "https://socialvision.tisyk.xyz/v1/real-avatar/groups/from-token" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应示例 (200 OK)

```json theme={null}
{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "GroupId": "string"
  }
}
```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.