私域人像 Avatar 接口参考 - SocialVision AI Gateway

⑩ 删除素材

DELETE /v1/private-avatar/assets/{id} 删除指定虚拟人像素材。

请求参数 (Query / Path)

string

required

AssetId

string

required

路由模型（必填）

请求示例 (cURL)

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)

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

string

required

GroupId

string

required

路由模型（必填）

请求示例 (cURL)

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)

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

string

required

AssetId（接口⑥ Result.Id）

string

required

路由模型（必填）

请求示例 (cURL)

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

响应示例 (200 OK)

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

string

required

GroupId

string

required

路由模型（必填）

请求示例 (cURL)

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

响应示例 (200 OK)

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

string

required

AssetId

请求体参数 (Body)

string

required

与路径 id 一致

string

名称

string

required

路由选择参数（固定传此值）

请求示例 (cURL)

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)

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

string

required

GroupId

请求体参数 (Body)

string

描述

string

required

与路径 id 一致

string

名称

string

required

路由选择参数（固定传此值）

请求示例 (JSON)

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

请求示例 (cURL)

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)

{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {}
}

⑦ 查询素材列表

POST /v1/private-avatar/assets/list 分页查询素材列表，支持按素材组、状态、名称筛选。

请求体参数 (Body)

object

过滤条件

integer

页码

integer

每页条数

string

排序字段

string

排序方向（asc / desc）

string

required

路由选择参数（固定传此值）

请求示例 (JSON)

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

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)

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

string

required

首字母大写

string

required

接口①返回的 Result.Id

string

素材备注名（可选）

string

required

素材公网可访问地址（字段名全大写 URL）

string

required

路由选择参数（固定传此值）

请求示例 (JSON)

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

请求示例 (cURL)

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)

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

object

过滤条件

integer

页码

integer

每页条数

string

required

路由选择参数（固定传此值）

请求示例 (JSON)

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

请求示例 (cURL)

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)

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

string

素材组描述（可选）

string

虚拟人像固定 AIGC，可省略

string

required

素材组名称（必填）

string

required

路由选择参数（固定传此值）

请求示例 (JSON)

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

请求示例 (cURL)

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)

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

string

required

演员认证完成后浏览器跳转地址（业务方自己的前端页面，必填）

string

H5 页面语言（可选）

string

required

路由选择参数（固定传此值）

请求示例 (cURL)

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)

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

string

required

接口⑪ Result.BytedToken（须在 120 秒内调用）

string

required

路由选择参数（固定传此值）

请求示例 (cURL)

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)

{
  "ResponseMetadata": {
    "Action": "string",
    "Error": {
      "Code": "string",
      "Message": "string"
    },
    "Region": "string",
    "RequestId": "string",
    "Service": "string",
    "Version": "string"
  },
  "Result": {
    "GroupId": "string"
  }
}

​⑩ 删除素材

​请求参数 (Query / Path)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑤ 删除素材组

​请求参数 (Query / Path)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑧ 查询素材状态

​请求参数 (Query / Path)

​请求示例 (cURL)

​响应示例 (200 OK)

​③ 查询单个素材组

​请求参数 (Query / Path)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑨ 更新素材

​请求参数 (Query / Path)

​请求体参数 (Body)

​请求示例 (cURL)

​响应示例 (200 OK)

​④ 更新素材组

​请求参数 (Query / Path)

​请求体参数 (Body)

​请求示例 (JSON)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑦ 查询素材列表

​请求体参数 (Body)

​请求示例 (JSON)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑥ 上传素材

​请求体参数 (Body)

​请求示例 (JSON)

​请求示例 (cURL)

​响应示例 (200 OK)

​② 查询素材组列表

​请求体参数 (Body)

​请求示例 (JSON)

​请求示例 (cURL)

​响应示例 (200 OK)

​① 创建素材组

​请求体参数 (Body)

​请求示例 (JSON)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑪ 生成真人认证链接

​请求体参数 (Body)

​请求示例 (cURL)

​响应示例 (200 OK)

​⑫ BytedToken 换取 GroupId

​请求体参数 (Body)

​请求示例 (cURL)

​响应示例 (200 OK)

⑩ 删除素材

请求参数 (Query / Path)

请求示例 (cURL)

响应示例 (200 OK)

⑤ 删除素材组

请求参数 (Query / Path)

请求示例 (cURL)

响应示例 (200 OK)

⑧ 查询素材状态

请求参数 (Query / Path)

请求示例 (cURL)

响应示例 (200 OK)

③ 查询单个素材组

请求参数 (Query / Path)

请求示例 (cURL)

响应示例 (200 OK)

⑨ 更新素材

请求参数 (Query / Path)

请求体参数 (Body)

请求示例 (cURL)

响应示例 (200 OK)

④ 更新素材组

请求参数 (Query / Path)

请求体参数 (Body)

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)

⑦ 查询素材列表

请求体参数 (Body)

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)

⑥ 上传素材

请求体参数 (Body)

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)

② 查询素材组列表

请求体参数 (Body)

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)

① 创建素材组

请求体参数 (Body)

请求示例 (JSON)

请求示例 (cURL)

响应示例 (200 OK)

⑪ 生成真人认证链接

请求体参数 (Body)

请求示例 (cURL)

响应示例 (200 OK)

⑫ BytedToken 换取 GroupId

请求体参数 (Body)

请求示例 (cURL)

响应示例 (200 OK)