> ## Documentation Index
> Fetch the complete documentation index at: https://api.xcompute.us/llms.txt
> Use this file to discover all available pages before exploring further.

# 真人人像素材

* 真人人像素材接口，通过同一入口完成三种操作
* 步骤一：创建真人认证 H5 会话，获取 h5\_link 和 byted\_token
* 步骤二：用户完成 H5 认证后，查询认证结果获取素材组 group\_id
* 步骤三：向 group\_id 批量提交真人素材进行审核

<RequestExample>
  ```bash cURL（步骤一：创建认证会话） theme={null} theme={null}
  curl --request POST \
    --url https://xcompute.us/v1/seedance2/real-avatar \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "callback_url": "https://example.com/callback",
      "project_name": "default"
    }'
  ```

  ```bash cURL（步骤二：查询认证结果） theme={null} theme={null}
  curl --request POST \
    --url https://xcompute.us/v1/seedance2/real-avatar \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "byted_token": "token_xxx",
      "project_name": "default"
    }'
  ```

  ```bash cURL（步骤三：提交真人素材） theme={null} theme={null}
  curl --request POST \
    --url https://xcompute.us/v1/seedance2/real-avatar \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "group_id": "group_from_validation",
      "project_name": "default",
      "asset_type": "Video",
      "assets": [
        {
          "url": "https://example.com/real-face-a.mp4",
          "name": "real-face-a"
        },
        {
          "url": "https://example.com/real-face-b.mp4",
          "name": "real-face-b"
        }
      ]
    }'
  ```

  ```python Python theme={null} theme={null}
  import requests

  url = "https://xcompute.us/v1/seedance2/real-avatar"
  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  # 步骤一：创建认证会话
  payload_step1 = {
      "callback_url": "https://example.com/callback",
      "project_name": "default"
  }
  response = requests.post(url, json=payload_step1, headers=headers)
  task_id = response.json()["data"]["id"]

  # 步骤二：查询认证结果（用户完成 H5 认证后）
  payload_step2 = {
      "byted_token": "token_xxx",
      "project_name": "default"
  }
  response = requests.post(url, json=payload_step2, headers=headers)
  group_id = response.json()["data"]["result"]["GroupId"]

  # 步骤三：提交真人素材
  payload_step3 = {
      "group_id": group_id,
      "project_name": "default",
      "asset_type": "Video",
      "assets": [
          {"url": "https://example.com/real-face-a.mp4", "name": "real-face-a"},
          {"url": "https://example.com/real-face-b.mp4", "name": "real-face-b"}
      ]
  }
  response = requests.post(url, json=payload_step3, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null} theme={null}
  const url = "https://xcompute.us/v1/seedance2/real-avatar";
  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  // 步骤一：创建认证会话
  const step1 = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify({
      callback_url: "https://example.com/callback",
      project_name: "default"
    })
  });
  const { data: { id: taskId } } = await step1.json();

  // 步骤二：查询认证结果（用户完成 H5 认证后）
  const step2 = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify({
      byted_token: "token_xxx",
      project_name: "default"
    })
  });
  const { data: { result: { GroupId: groupId } } } = await step2.json();

  // 步骤三：提交真人素材
  const step3 = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify({
      group_id: groupId,
      project_name: "default",
      asset_type: "Video",
      assets: [
        { url: "https://example.com/real-face-a.mp4", name: "real-face-a" },
        { url: "https://example.com/real-face-b.mp4", name: "real-face-b" }
      ]
    })
  });
  console.log(await step3.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200（步骤一：创建认证会话） theme={null} theme={null}
  {
    "code": 200,
    "data": {
      "id": "task_01K...",
      "status": "completed"
    }
  }
  ```

  ```json 200（步骤三：提交素材） theme={null} theme={null}
  {
    "code": 200,
    "data": {
      "id": "task_01K...",
      "object": "seedance.avatar.asset.task",
      "status": "processing",
      "progress": 10,
      "model": "doubao-seedance-2.0"
    }
  }
  ```

  ```json 400 theme={null} theme={null}
  {
    "error": {
      "code": 400,
      "message": "请求参数无效",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null} theme={null}
  {
    "error": {
      "code": 401,
      "message": "身份验证失败，请检查您的API密钥",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null} theme={null}
  {
    "error": {
      "code": 402,
      "message": "账户余额不足，请充值后再试",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null} theme={null}
  {
    "error": {
      "code": 429,
      "message": "请求过于频繁，请稍后再试",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null} theme={null}
  {
    "error": {
      "code": 500,
      "message": "服务器内部错误，请稍后重试",
      "type": "server_error"
    }
  }
  ```
</ResponseExample>

## 认证

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用 Bearer Token 进行认证

  获取 API Key：

  访问 [API Key 管理页面](https://xcompute.us/keys) 获取您的 API Key

  使用时在请求头中添加：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 请求参数

### 步骤一：创建真人认证会话

<ParamField body="callback_url" type="string" required>
  认证完成后的回调 URL

  用户完成 H5 认证后，系统会向该地址发送回调通知
</ParamField>

<ParamField body="project_name" type="string" default="default">
  项目名称

  默认值：`default`
</ParamField>

#### 响应

<ResponseField name="code" type="integer">
  响应状态码，成功时为 200
</ResponseField>

<ResponseField name="data" type="object">
  任务信息

  <Expandable title="字段说明">
    <ResponseField name="id" type="string">
      本地任务 ID，用于查询 H5 链接和 `byted_token`
    </ResponseField>

    <ResponseField name="status" type="string">
      任务状态，初始为 `completed`（会话创建成功）
    </ResponseField>
  </Expandable>
</ResponseField>

查询该任务可获得 H5 认证链接：

```http theme={null} theme={null}
GET /v1/tasks/task_01K...
```

```json theme={null} theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "result": {
      "byted_token": "token_xxx",
      "h5_link": "https://...",
      "raw_response": {}
    }
  }
}
```

***

### 步骤二：查询真人认证结果

<ParamField body="byted_token" type="string" required>
  从步骤一任务结果中获取的认证令牌

  用户完成 H5 认证后，通过 `GET /v1/tasks/{id}` 查询任务获取 `byted_token`，再用此字段查询认证结果，拿到真人素材组 `GroupId`
</ParamField>

<ParamField body="project_name" type="string" default="default">
  项目名称

  默认值：`default`
</ParamField>

***

### 步骤三：批量提交真人素材

<ParamField body="group_id" type="string" required>
  真人素材组 ID

  从步骤二认证结果中获取的 `GroupId`
</ParamField>

<ParamField body="project_name" type="string" default="default">
  项目名称

  默认值：`default`
</ParamField>

<ParamField body="asset_type" type="string" default="Video">
  素材类型

  可选值：

  * `Video` - 视频素材（默认，推荐用于真人人像）
  * `Image` - 图片素材

  默认值：`Video`
</ParamField>

<ParamField body="assets" type="array" required>
  素材列表，支持一次提交多个素材

  <Expandable title="字段说明">
    <ParamField body="url" type="string" required>
      素材 URL，需为公网可访问链接
    </ParamField>

    <ParamField body="name" type="string" required>
      素材名称
    </ParamField>
  </Expandable>

  示例：

  ```json theme={null} theme={null}
  {
    "assets": [
      {
        "url": "https://example.com/avatar-a.png",
        "name": "avatar-a"
      },
      {
        "url": "https://example.com/avatar-b.png",
        "name": "avatar-b"
      }
    ]
  }
  ```
</ParamField>

#### 响应

<ResponseField name="code" type="integer">
  响应状态码，成功时为 200
</ResponseField>

<ResponseField name="data" type="object">
  素材审核任务信息

  <Expandable title="字段说明">
    <ResponseField name="id" type="string">
      本地任务 ID，用于后续查询素材审核状态
    </ResponseField>

    <ResponseField name="object" type="string">
      任务对象类型，固定为 `seedance.avatar.asset.task`
    </ResponseField>

    <ResponseField name="status" type="string">
      任务初始状态，提交后为 `processing`
    </ResponseField>

    <ResponseField name="progress" type="integer">
      任务进度（0 \~ 100）
    </ResponseField>

    <ResponseField name="model" type="string">
      当前使用的模型名称
    </ResponseField>
  </Expandable>
</ResponseField>

## 查询审核结果

素材提交后为异步审核任务，使用 [获取任务状态](/cn/api-reference/tasks/status) 接口查询：

### 全部通过

```json theme={null} theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "completed",
    "progress": 100,
    "result": {
      "assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Active"
        }
      ],
      "usable_assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Active"
        }
      ],
      "failed_assets": []
    }
  }
}
```

### 部分失败

```json theme={null} theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01K...",
    "status": "failed",
    "progress": 100,
    "result": {
      "assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        },
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Failed"
        }
      ],
      "usable_assets": [
        {
          "asset_id": "asset_a",
          "asset_url": "asset://asset_a",
          "status": "Active"
        }
      ],
      "failed_assets": [
        {
          "asset_id": "asset_b",
          "asset_url": "asset://asset_b",
          "status": "Failed"
        }
      ]
    },
    "error": {
      "code": "task_failed",
      "message": "部分素材审核失败"
    }
  }
}
```

<Note>
  * `result.usable_assets[].asset_url` 可直接用于 Seedance 2.0 视频生成
  * `result.failed_assets` 中的素材需更换源文件或重新提交
</Note>

## 审核后使用素材

审核通过后，将 `asset://...` URL 直接传入 [Seedance 2.0 视频生成](/cn/api-reference/videos/doubao-seedance-2-0/generation) 接口：

```json theme={null} theme={null}
{
  "model": "doubao-seedance-2.0-face",
  "prompt": "使用参考人像生成视频",
  "image_with_roles": [
    {
      "url": "asset://asset_a",
      "role": "reference_image"
    }
  ]
}
```

<Note>
  * 真人人像素材建议配合 `doubao-seedance-2.0-face` 或 `doubao-seedance-2.0-fast-face` 模型使用
  * 服务端识别到 `asset://` 前缀后，会直接提交官方生成任务，不会再次触发素材审核
</Note>