---
title: "Seedance Action dispatcher (POST)"
method: POST
path: "/api/v3"
tags: ["Seedance Volc Compatible"]
---

# Seedance Action dispatcher (POST)

`POST /api/v3`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/api/v3`
- Auth: HTTP bearer

Dispatches Volc-style Action requests with TokenLab Bearer authentication. Real-person validation and material asset Actions use Version=2024-01-01 and are POST-only. The same POST contract is also available at the API root for endpoint-only migration from Volcengine.

## Query parameters

- `Action` 'CreateContentsGenerationsTasks' | 'GetContentsGenerationsTask' | 'ListContentsGenerationsTasks' | 'DeleteContentsGenerationsTasks' | 'CreateVisualValidateSession' | 'GetVisualValidateResult' | 'CreateAssetGroup' | 'ListAssetGroups' | 'GetAssetGroup' | 'UpdateAssetGroup' | 'DeleteAssetGroup' | 'CreateAsset' | 'ListAssets' | 'GetAsset' | 'UpdateAsset' | 'DeleteAsset'
- `Version` string

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- union
  - VolcCreateVisualValidateSessionRequest
    - `CallbackURL` string, uri, required: Public HTTPS URL opened by the H5 flow after validation. Official callback query names are preserved.
    - `ProjectName` string: Case-sensitive project name. Omit to use default.
  - VolcGetVisualValidateResultRequest
    - `BytedToken` string, required: Opaque token returned by CreateVisualValidateSession. It is valid for 30 minutes and scoped to the authenticated organization, actor, and ProjectName.
    - `ProjectName` string: Must match the ProjectName used to create the token.
  - VolcMaterialActionRequest: PascalCase request body for the material Action selected by the Action query parameter. Required fields depend on the selected Action.
    - `Id` string: Asset or Asset Group identifier for get, update, and delete Actions.
    - `Name` string
    - `Description` string
    - `GroupType` 'AIGC' | 'LivenessFace'
    - `GroupId` string
    - `URL` string, uri
    - `AssetType` 'Image' | 'Video' | 'Audio'
    - `Filter` object
      - `GroupIds` string[]
      - `GroupType` 'AIGC' | 'LivenessFace'
      - `Statuses` string[]
      - `Name` string
    - `PageNumber` integer
    - `PageSize` integer
    - `SortBy` 'CreateTime' | 'UpdateTime' | 'GroupId'
    - `SortOrder` 'Desc' | 'Asc'
    - `ProjectName` string: Project isolation scope within the authenticated organization.
  - object

## Response `200`

Action response. Content-generation actions return task JSON; real-person validation and material asset actions return the official ResponseMetadata + Result envelope.

- union
  - VolcSeedanceCreateTaskResponse
    - `id` string, required
  - VolcSeedanceTask
    - `id` string, required
    - `model` string, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'expired', required
    - `content` object
      - `video_url` string, uri
      - `last_frame_url` string, uri
    - `seed` integer
    - `resolution` string
    - `ratio` string
    - `duration` string
    - `frames` integer
    - `framespersecond` integer
    - `generate_audio` boolean
    - `tools` object
      - `type` 'web_search'
    - `safety_identifier` string
    - `draft` boolean
    - `draft_task_id` string
    - `service_tier` string
    - `execution_expires_after` integer
    - `usage` object
      - `completion_tokens` integer
      - `total_tokens` integer
      - `tool_usage` object
        - `web_search` integer
    - `error` object
      - `code` string, required
      - `message` string, required
    - `created_at` integer: Unix timestamp in seconds.
    - `updated_at` integer: Unix timestamp in seconds.
  - VolcSeedanceTaskListResponse
    - `items` VolcSeedanceTask[], required
      - `id` string, required
      - `model` string, required
      - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'expired', required
      - `content` object
        - `video_url` string, uri
        - `last_frame_url` string, uri
      - `seed` integer
      - `resolution` string
      - `ratio` string
      - `duration` string
      - `frames` integer
      - `framespersecond` integer
      - `generate_audio` boolean
      - `tools` object
        - `type` 'web_search'
      - `safety_identifier` string
      - `draft` boolean
      - `draft_task_id` string
      - `service_tier` string
      - `execution_expires_after` integer
      - `usage` object
        - `completion_tokens` integer
        - `total_tokens` integer
        - `tool_usage` object
          - `web_search` integer
      - `error` object
        - `code` string, required
        - `message` string, required
      - `created_at` integer: Unix timestamp in seconds.
      - `updated_at` integer: Unix timestamp in seconds.
    - `total` integer, required
  - VolcCreateVisualValidateSessionResponse
    - `ResponseMetadata` VolcVisualValidationResponseMetadata, required
      - `RequestId` string, required: TokenLab request identifier.
      - `Action` 'CreateVisualValidateSession' | 'GetVisualValidateResult', required
      - `Version` '2024-01-01', required
      - `Service` 'ark', required
      - `Region` 'cn-beijing', required
    - `Result` object, required
      - `BytedToken` string, required
      - `H5Link` string, uri, required
      - `CallbackURL` string, uri, required
  - VolcGetVisualValidateResultResponse
    - `ResponseMetadata` VolcVisualValidationResponseMetadata, required
      - `RequestId` string, required: TokenLab request identifier.
      - `Action` 'CreateVisualValidateSession' | 'GetVisualValidateResult', required
      - `Version` '2024-01-01', required
      - `Service` 'ark', required
      - `Region` 'cn-beijing', required
    - `Result` object, required
      - `GroupId` string, required: TokenLab-mapped real-person Asset Group ID returned after successful validation.
  - VolcMaterialActionResponse
    - `ResponseMetadata` VolcMaterialResponseMetadata, required
      - `RequestId` string, required
      - `Action` 'CreateAssetGroup' | 'ListAssetGroups' | 'GetAssetGroup' | 'UpdateAssetGroup' | 'DeleteAssetGroup' | 'CreateAsset' | 'ListAssets' | 'GetAsset' | 'UpdateAsset' | 'DeleteAsset', required
      - `Version` '2024-01-01', required
      - `Service` 'ark', required
      - `Region` 'cn-beijing', required
    - `Result` object, required: Action-dependent result. List Actions return Items, TotalCount, PageNumber, and PageSize; create and update Actions return Id; delete Actions return an empty object.

## Other responses

- `400`: Invalid request
- `401`: Missing or unsupported authentication
- `403`: Access denied
- `405`: Action does not support this HTTP method
- `409`: Material group mapping conflict
- `422`: Real-person validation is unavailable for the current account configuration
- `429`: Rate limit exceeded
- `500`: Internal error
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)