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

# Seedance Real-Person Asset Validation API

> Create a Volcengine H5 real-person validation session, obtain the Asset Group ID, and upload real-person assets to that group for Seedance workflows

## Overview

Use this flow when you need to upload real-person portrait assets into a private Seedance asset group. The validation
step creates an `Asset Group ID` that is bound to one real person. After you get the `GroupId`, upload the person's
image, video, or audio assets with [Seedance Asset Upload API](/models/seedance/asset-upload) by passing `group_id`.

## Flow

1. Call `POST /api/v1/client/job/visual-validate-session` with your `callback_url`.
2. Open the returned `H5Link` for the end user and complete real-person face validation.
3. After validation, the H5 page redirects to your `callback_url` with result parameters such as `bytedToken` and
   `resultCode`.
4. When `resultCode` is `10000`, call `GET /api/v1/client/job/visual-validate-result` with the `byted_token` to obtain
   `GroupId`.
5. Call [Seedance Asset Upload API](/models/seedance/asset-upload) and pass the returned `GroupId` as `group_id`. The
   upload flow is then the same as regular asset upload.
6. Poll [Seedance Asset Info API](/models/seedance/asset-info) until `Status` becomes `Active`, then use the returned
   `AssetId` in Seedance generation requests.

<Note>
  The H5 validation link is valid for 120 seconds. If validation fails or the link expires, create a new validation session.
</Note>

<Tip>
  You can set the page language by appending or updating the `lng` parameter in `H5Link`. Supported values are `zh`, `en`, and `zh-Hant`; the default is `zh`.
</Tip>

## Step 1: Create Validation Session

Call this endpoint to create a Volcengine H5 validation link.

### Request Body

<ParamField body="callback_url" type="string" required>
  Callback URL opened after the end user completes the H5 validation page. The callback receives validation result parameters.
</ParamField>

### Request Example

```json theme={null}
{
  "callback_url": "https://example.com/callback/seedance-visual-validation"
}
```

### Response Example

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "BytedToken": "202603311449168C23BA26**************",
    "H5Link": "https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh",
    "CallbackURL": "https://example.com/callback/seedance-visual-validation"
  }
}
```

## Callback Parameters

After the user completes validation, the H5 page redirects to your callback URL. A successful callback commonly looks
like:

```text theme={null}
https://example.com/callback/seedance-visual-validation?bytedToken=********&resultCode=10000&algorithmBaseRespCode=0&reqMeasureInfoValue=1&verify_type=real_time
```

| Parameter               | Description                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `bytedToken`            | Unique credential for this validation. Use it as `byted_token` when querying the validation result. |
| `resultCode`            | Validation result. `10000` means validation passed.                                                 |
| `algorithmBaseRespCode` | Service-side sub error code. Check it when `resultCode` indicates a server-side error.              |
| `verify_type`           | Validation type. Current value is `real_time`.                                                      |

## Step 2: Get Validation Result

Call this endpoint after the callback indicates that validation passed. It returns the `GroupId` created for this real
person.

### Query Parameters

<ParamField query="byted_token" type="string" required>
  `BytedToken` returned by the validation session endpoint or `bytedToken` received in your callback URL.
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/visual-validate-result?byted_token=202603311449168C23BA26**************" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

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

  API_KEY = "YOUR_API_KEY"

  response = requests.get(
      "https://api.crun.ai/api/v1/client/job/visual-validate-result",
      params={"byted_token": "202603311449168C23BA26**************"},
      headers={"X-API-KEY": API_KEY},
  )

  print(response.json())
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "GroupId": "group-20260331145705-*****"
  }
}
```

## Step 3: Upload Assets To Group

Use the returned `GroupId` as `group_id` when uploading assets:

```json theme={null}
{
  "name": "fashion-model-front",
  "asset_type": "Image",
  "asset_url": "https://example.com/assets/fashion-model-front.jpg",
  "group_id": "group-20260331145705-*****"
}
```

Each real-person `Asset Group` is bound to one real face. When an asset is uploaded to the group, the upstream service
compares the uploaded face with the baseline face collected during validation. The upload may fail if the asset is not
the same person or if multiple faces are detected.

## Related Resources

<CardGroup cols={2}>
  <Card title="Asset Upload" icon="upload" href="/models/seedance/asset-upload">
    Upload image, video, and audio assets, including real-person assets with `group_id`
  </Card>

  <Card title="Asset Info" icon="magnifying-glass" href="/models/seedance/asset-info">
    Query upload status and wait for the asset to become active
  </Card>
</CardGroup>


## OpenAPI

````yaml models/seedance/visual-validate.json post /api/v1/client/job/visual-validate-session
openapi: 3.0.0
info:
  title: Seedance Real-Person Asset Validation API
  description: >-
    API documentation for creating a real-person validation session and
    retrieving the Asset Group ID used by Seedance real-person asset uploads
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API Server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/visual-validate-session:
    post:
      summary: Create a real-person H5 validation session
      description: >-
        Creates a Volcengine H5 validation link. Open the returned `H5Link` for
        the end user. After validation passes, use the returned or callback
        `BytedToken` to query the Asset Group ID.
      operationId: seedance/visual-validate-session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - callback_url
              properties:
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    Callback URL opened after the end user completes H5
                    validation. The callback receives validation result
                    parameters such as `bytedToken` and `resultCode`.
                  example: https://example.com/callback/seedance-visual-validation
            example:
              callback_url: https://example.com/callback/seedance-visual-validation
      responses:
        '200':
          description: Validation session created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          BytedToken:
                            type: string
                            description: >-
                              Validation credential. Use it to query the
                              validation result and Asset Group ID.
                            example: 202603311449168C23BA26**************
                          H5Link:
                            type: string
                            format: uri
                            description: >-
                              H5 validation link. It is valid for 120 seconds.
                              You can set the page language with the `lng`
                              parameter: `zh`, `en`, or `zh-Hant`; default is
                              `zh`.
                            example: >-
                              https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh
                          CallbackURL:
                            type: string
                            format: uri
                            description: Callback URL used by the validation session.
                            example: >-
                              https://example.com/callback/seedance-visual-validation
              example:
                code: 200
                message: success
                data:
                  BytedToken: 202603311449168C23BA26**************
                  H5Link: >-
                    https://visual.volcengine.com/validate?...&bytedToken=202603311449168C23BA26**************&lng=zh
                  CallbackURL: https://example.com/callback/seedance-visual-validation
        '422':
          description: Validation Error
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          enum:
            - 200
            - 401
            - 402
            - 404
            - 422
            - 429
            - 455
            - 500
            - 501
            - 505
          description: >-
            Response status code


            - **200**: Success - Request has been processed successfully

            - **401**: Unauthorized - Authentication credentials are missing or
            invalid

            - **402**: Insufficient Credits - Account does not have enough
            credits to perform the operation

            - **404**: Not Found - The requested resource or endpoint does not
            exist

            - **422**: Validation Error - The request parameters failed
            validation checks

            - **429**: Rate Limited - Request limit has been exceeded for this
            resource

            - **455**: Service Unavailable - System is currently undergoing
            maintenance

            - **500**: Server Error - An unexpected error occurred while
            processing the request

            - **501**: Generation Failed - Content generation task failed

            - **505**: Feature Disabled - The requested feature is currently
            disabled
        message:
          type: string
          description: Response message, error description when failed
          example: success
  responses:
    Error:
      description: Server Error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        All APIs require authentication via API Key.


        Get API Key:

        1. Visit [API Key Management Page](https://crun.ai/user-api-key) to get
        your API Key


        Usage:

        Add to request header:


        x-api-key: YOUR_API_KEY


        Note:

        - Keep your API Key secure and do not share it with others

        - If you suspect your API Key has been compromised, reset it immediately
        in the management page

````