Seedance 2.0 原厂协议

curl --request POST \
  --url https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "model": "<string>",
  "content": [
    {}
  ],
  "duration": 123,
  "resolution": "<string>",
  "ratio": "<string>",
  "generate_audio": true,
  "watermark": true
}
'

import requests

url = "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks"

payload = {
    "model": "<string>",
    "content": [{}],
    "duration": 123,
    "resolution": "<string>",
    "ratio": "<string>",
    "generate_audio": True,
    "watermark": True
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "<authorization>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'},
  body: JSON.stringify({
    model: '<string>',
    content: [{}],
    duration: 123,
    resolution: '<string>',
    ratio: '<string>',
    generate_audio: true,
    watermark: true
  })
};

fetch('https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'content' => [
        [
                
        ]
    ],
    'duration' => 123,
    'resolution' => '<string>',
    'ratio' => '<string>',
    'generate_audio' => true,
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "<authorization>")
  .body("{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = '<authorization>'
request.body = "{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}"

response = http.request(request)
puts response.read_body

POST

bytedance

contents

generations

tasks

Seedance 2.0 原厂协议

curl --request POST \
  --url https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "model": "<string>",
  "content": [
    {}
  ],
  "duration": 123,
  "resolution": "<string>",
  "ratio": "<string>",
  "generate_audio": true,
  "watermark": true
}
'

import requests

url = "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks"

payload = {
    "model": "<string>",
    "content": [{}],
    "duration": 123,
    "resolution": "<string>",
    "ratio": "<string>",
    "generate_audio": True,
    "watermark": True
}
headers = {
    "Content-Type": "<content-type>",
    "Authorization": "<authorization>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', Authorization: '<authorization>'},
  body: JSON.stringify({
    model: '<string>',
    content: [{}],
    duration: 123,
    resolution: '<string>',
    ratio: '<string>',
    generate_audio: true,
    watermark: true
  })
};

fetch('https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => '<string>',
    'content' => [
        [
                
        ]
    ],
    'duration' => 123,
    'resolution' => '<string>',
    'ratio' => '<string>',
    'generate_audio' => true,
    'watermark' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks")
  .header("Content-Type", "<content-type>")
  .header("Authorization", "<authorization>")
  .body("{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["Authorization"] = '<authorization>'
request.body = "{\n  \"model\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"duration\": 123,\n  \"resolution\": \"<string>\",\n  \"ratio\": \"<string>\",\n  \"generate_audio\": true,\n  \"watermark\": true\n}"

response = http.request(request)
puts response.read_body

本文档整合了 Seedance 2.0 视频生成 API 及其配套的两种素材管理 API，为开发者提供一站式的协议参考。三部分内容的关系如下：

视频生成 API：核心能力，通过 Seedance 2.0 / Seedance 2.0-fast 模型生成视频。
虚拟人像素材 API：将图片、视频或音频创建为可被 Seedance 引用的素材，生成时使用 asset://<Id> 引用。
真人素材 API：用户完成 H5 真人验证后，将该真人的画像创建为可被 Seedance 引用的素材，同样使用 asset://<Id> 引用。

素材 API 创建的 asset 可被视频生成 API 引用，实现”先建素材 → 再生成视频”的完整流程。

一、视频生成 API

1.1 调用方式

创建任务：

POST https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks

查询任务：

GET https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks/{id}

1.2 支持模型

模型	说明
seedance-2.0	标准版
seedance-2.0-fast	快速版

官方文档参考：https://www.volcengine.com/docs/82379/1520757?lang=zh

1.3 请求头

Content-Type

string

必填

枚举值: application/json

Authorization

string

必填

Bearer 身份验证格式: Bearer {{API 密钥}}。

1.4 请求体

model

string

必填

模型名称。可选值：seedance-2.0、seedance-2.0-fast

content

array

必填

多模态内容数组，支持文本、图片、视频、音频等类型。每项包含 type 字段和对应内容。支持的类型：

text：文本提示词，包含 text 字段
image_url：图片输入，包含 image_url.url 字段，可选 role 字段（如 reference_image）
video_url：视频输入，包含 video_url.url 字段，可选 role 字段（如 reference_video）
audio_url：音频输入，包含 audio_url.url 字段，可选 role 字段（如 reference_audio）

URL 字段也支持 asset://<Id> 格式引用已创建的素材。

duration

integer

默认值:5

生成视频时长（秒）。范围 [4, 15]

resolution

string

默认值:"720p"

视频分辨率。1080p 仅支持标准版。可选值：480p, 720p, 1080p

ratio

string

默认值:"adaptive"

生成视频的宽高比。可选值：16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive

generate_audio

boolean

默认值:true

是否生成与画面同步的声音。true 时模型基于文本与视觉内容自动生成匹配的人声、音效及背景音乐。

watermark

boolean

默认值:false

生成视频是否包含水印。

1.5 REST API 示例

创建任务：

curl -X POST 'https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  -d @- << EOF
{
  "content": [
    {
      "text": "A cat walking through a sunny garden",
      "type": "text"
    }
  ],
  "duration": 5,
  "model": "seedance-2.0",
  "resolution": "480p"
}
EOF

查询任务：

curl -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <key>' \
  'https://api.highwayapi.ai/v3/bytedance/contents/generations/tasks/975de73b-85ff-47f1-b199-737b72fe92da'

1.6 SDK 示例

import os
import time
# Install SDK:  pip install 'volcengine-python-sdk[ark]'
from volcenginesdkarkruntime import Ark

client = Ark(
    base_url='https://api.highwayapi.ai/v3/bytedance',
    api_key=os.environ.get("YOUR_API_KEY"),
)

if __name__ == "__main__":
    print("----- create request -----")
    create_result = client.content_generation.tasks.create(
        model="seedance-2.0-fast",
        content=[
            {
                "type": "text",
                "text": "全程使用视频1的第一视角构图，全程使用音频1作为背景音乐。第一人称视角果茶宣传广告...",
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
                },
                "role": "reference_image",
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
                },
                "role": "reference_image",
            },
            {
                "type": "video_url",
                "video_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
                },
                "role": "reference_video",
            },
            {
                "type": "audio_url",
                "audio_url": {
                    "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
                },
                "role": "reference_audio",
            },
        ],
        generate_audio=True,
        ratio="16:9",
        duration=11,
        watermark=True,
    )
    print(create_result)

    # Polling query section
    print("----- polling task status -----")
    task_id = create_result.id
    while True:
        get_result = client.content_generation.tasks.get(task_id=task_id)
        status = get_result.status
        if status == "succeeded":
            print("----- task succeeded -----")
            print(get_result)
            break
        elif status == "failed":
            print("----- task failed -----")
            print(f"Error: {get_result.error}")
            break
        else:
            print(f"Current status: {status}, Retrying after 30 seconds...")
            time.sleep(30)

二、虚拟人像素材 API

2.1 适用范围

本接口用于将图片、视频或音频创建为 Seedance 可引用的虚拟人像素材。素材创建完成并返回 Active 后，使用 asset://<Id> 引用。

2.2 调用方式

统一入口：

POST https://api.highwayapi.ai/v3/synthetic/bytedance/ark?Action={Action}&Version=2024-01-01
Content-Type: application/json

2.3 鉴权

客户只需要传平台 API Key：Authorization: Bearer <key>

2.4 支持 Action

Action	方法	说明
CreateAsset	POST	创建虚拟人像素材，返回平台 asset id。
GetAsset	POST	查询素材状态。

2.5 通用响应结构

成功响应：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误响应：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "URL is required"
    }
  }
}

2.6 创建资产 (CreateAsset)

使用公网可下载的图片、视频或音频 URL 创建虚拟人像素材。CreateAsset 为异步处理，创建后建议调用 GetAsset 轮询状态。 Request：

curl -X POST 'https://api.highwayapi.ai/v3/synthetic/bytedance/ark?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "URL": "https://your-cdn.example.com/assets/reference-image.png",
    "AssetType": "Image",
    "Name": "product_reference_image"
  }'

Request 字段：

字段	类型	必填	说明
URL	string	是	素材 URL，平台和上游服务必须能从公网下载。
AssetType	string	否	支持 Image、Video、Audio；不传时默认 Image。
Name	string	否	客户侧素材名称，用于区分和幂等匹配。
ProjectName	string	否	可传但会被平台忽略，平台统一使用默认项目。

素材建议：

类型	建议
图片	JPG / PNG；URL 可公网下载；内容应符合平台和上游内容安全要求。
视频	MP4 等常见格式；分辨率、时长和编码需满足上游 Seedance 资产要求。
音频	MP3 / WAV 等常见格式；URL 可公网下载。

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Image",
    "Name": "product_reference_image",
    "Status": "Processing"
  }
}

Response 字段：

字段	说明
Id	平台 asset id，后续使用 `asset://<Id>` 引用。
Status	素材状态，初始通常为 Processing。
AssetType	素材类型。
Name	创建时传入的素材名称。

重复创建行为： 同一账号下，CreateAsset 会在同一上游供应商绑定内按 URL + AssetType + Name 精确幂等：

场景	行为
命中同一上游供应商，且 URL、AssetType、Name 均相同	返回已创建的同一个平台 asset id。
URL、AssetType 或 Name 任一不同	按新的创建请求处理。

常见错误：

HTTP	Code	Message	说明
400	InvalidParameter	URL is required	未传 URL。
404	InvalidAction	Action is not supported for bytedance asset	Action 不在虚拟人像素材白名单内。
503	NoProviderAvailable	no asset provider available	当前没有可用素材供应商，请稍后重试或联系平台支持。

上游素材校验失败时，平台会透传上游错误。例如视频分辨率过低时，上游可能返回类似 InvalidParameter.HeightTooSmall 的错误。

2.7 查询资产状态 (GetAsset)

查询素材状态。建议创建后轮询到 Status=Active 再用于视频生成。 Request：

curl -X POST 'https://api.highwayapi.ai/v3/synthetic/bytedance/ark?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-20260701111803-yqveg"
  }'

Request 字段：

字段	类型	必填	说明
Id	string	是	CreateAsset 返回的平台 asset id。

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Image",
    "Name": "product_reference_image",
    "Status": "Active"
  }
}

失败状态示例：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-20260701111803-yqveg",
    "AssetType": "Video",
    "Name": "product_reference_video",
    "Status": "Failed",
    "ErrorMessage": "asset validation failed"
  }
}

Status 说明：

Status	说明
Processing	处理中，继续轮询。
Active	素材可用于 Seedance 视频生成。
Failed	素材创建失败，响应可能包含 ErrorMessage。

常见错误：

HTTP	Code	Message	说明
400	InvalidParameter	Id is required	未传 Id。
404	AssetNotFound	asset not found	asset 不存在或不属于当前账号。
409	AssetUnavailable	asset unavailable, please upload again: …	当前素材绑定的上游命名空间不可用，需要重新创建素材。

2.8 Seedance 生成中引用虚拟人像素材

当 GetAsset 返回 Active 后，可在 Seedance 请求中使用：

{
  "model": "seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "Create a product video with a clean studio background."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-20260701111803-yqveg"
      },
      "role": "reference_image"
    }
  ]
}

字段	适用素材
content[].image_url.url	Image
content[].video_url.url	Video
content[].audio_url.url	Audio

生成侧常见错误：

HTTP	Code / reason	Message / details	说明
400	INVALID_REQUEST_BODY	asset not found: <asset_id>	asset 不存在，或不属于当前账号。
400	INVALID_REQUEST_BODY	asset not ready: <asset_id> (status=Processing)	asset 尚未 Active，需要继续轮询。
400	INVALID_REQUEST_BODY	all assets in one request must belong to the same provider account	同一请求中引用了不同供应商账号的 asset。
400	INVALID_REQUEST_BODY	asset unavailable, please upload again: …	asset 绑定的上游命名空间不可用，不会 fallback 到其他供应商。

2.9 排障清单

现象	优先检查
InvalidAction	是否使用 /v3/synthetic/bytedance/ark，且 Action 为 CreateAsset 或 GetAsset。
URL is required	CreateAsset 请求体是否传入 URL。
素材创建失败	素材 URL 是否公网可下载；格式、分辨率、时长是否满足上游要求；内容是否符合安全要求。
asset not found	API Key 是否属于创建该 asset 的同一账号；asset:// 后的 id 是否为 Result.Id。
asset not ready	GetAsset 是否已经返回 Active。
多素材请求失败	同一个生成请求内是否混用了不同供应商账号创建的 asset。
带 asset 生成失败	asset 是否属于当前账号且状态为 Active；若提示 asset unavailable，需要重新创建素材。

三、真人素材 API

3.1 适用范围

本接口用于用户完成 H5 真人验证后，将该同一真人的画像创建为 Seedance 可引用的真人素材。素材状态为 Active 后，使用 asset://<Id> 引用。

3.2 调用方式

统一入口：

POST https://api.highwayapi.ai/v3/bytedance/ark?Action={Action}&Version=2024-01-01

3.3 鉴权

客户只需要传平台 API Key：Authorization: Bearer <key>

3.4 支持 Action

Action	方法	说明
CreateVisualValidateSession	POST	创建 H5 真人验证会话，返回 H5Link。
GetVisualValidateResult	POST	使用 H5 回调中的 BytedToken 换取验证结果和 AssetGroupID。
CreateAsset	POST	在资产组下创建资产。
GetAsset	POST	查询资产状态。

3.5 通用响应结构

成功响应：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {}
}

错误响应：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "GroupId is required"
    }
  }
}

3.6 创建 H5 真人验证会话 (CreateVisualValidateSession)

Request：

curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "CallbackURL": "https://your-app.example.com/liveness/done"
  }'

Request 字段：

字段	类型	必填	说明
CallbackURL	string	是	用户完成 H5 真人验证后跳转回客户侧页面。

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01"
  },
  "Result": {
    "H5Link": "https://example.com/liveness?token=...",
    "BytedToken": "xxx",
    "ExpiresInSec": 120,
    "ExpiresAt": "xxx"
  }
}

Response 字段：

字段	说明
H5Link	客户前端打开该链接，让用户完成真人验证。
BytedToken	真人验证会话 token，后续调用 GetVisualValidateResult 时传入。
ExpiresInSec	有效期秒数，通常为 120 秒。
ExpiresAt	过期时间戳。

用户完成 H5 真人验证：客户前端打开 H5Link 后，用户按页面引导完成真人验证。H5 页面完成后会跳转到创建会话时传入的 CallbackURL。建议客户侧仍以 GetVisualValidateResult 的结果作为真人验证是否可用于创建素材的最终依据。

3.7 获取验证结果 (GetVisualValidateResult)

使用 BytedToken 查询真人验证结果，获取后续创建素材需要的 GroupId。 Request：

curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "BytedToken": "xxx"
  }'

Request 字段：

字段	类型	必填	说明
BytedToken	string	是	CreateVisualValidateSession 返回的 token。

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetVisualValidateResult",
    "Version": "2024-01-01"
  },
  "Result": {
    "GroupId": "group-xxx-xxx"
  }
}

常见错误：

HTTP	Code	Message	说明
400	InvalidParameter	BytedToken is required	未传 BytedToken。
404	SessionNotFound	liveness session not found	token 不存在或不属于当前账号。
410	SessionExpired	liveness session expired	token 已过期，需要重新创建 H5 真人验证会话。
409	AssetUnavailable	asset unavailable, please upload again: …	当前素材会话不可用，需要重新发起认证。

3.8 创建资产 (CreateAsset)

使用 GroupId 和真人画像 URL 创建素材。CreateAsset 是异步处理，创建后建议调用 GetAsset 轮询素材状态。 Request：

curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "group-xxx-xxx",
    "URL": "https://your-cdn.example.com/portraits/user123.jpg",
    "AssetType": "Image",
    "Name": "user_123_portrait"
  }'

Request 字段：

字段	类型	必填	说明
GroupId	string	是	GetVisualValidateResult 返回的 GroupId。
URL	string	是	真人画像图片 URL，平台必须能公网下载。
AssetType	string	否	素材类型，当前仅支持 Image；不传时默认 Image。
Name	string	否	素材名称。

图片建议：

项	建议
格式	JPG / PNG
可访问性	公网可下载，不能依赖客户内网鉴权。
内容	应为完成 H5 真人验证的同一真人。

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "CreateAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-xxx-xxx",
    "AssetType": "Image",
    "Name": "user_123_portrait",
    "Status": "Processing"
  }
}

重复创建行为： 同一账号下，CreateAsset 会按 GroupId + URL + AssetType + Name 精确幂等：

场景	行为
GroupId、URL、AssetType、Name 均相同	返回已创建的同一个平台 asset id。
URL、AssetType 或 Name 任一不同	按新的创建请求处理，并继续进行真人一致性校验。

3.9 查询资产状态 (GetAsset)

查询素材状态。建议创建后轮询到 Status=Active 再用于视频生成。 Request：

curl -X POST 'https://api.highwayapi.ai/v3/bytedance/ark?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-xxx-yqveg"
  }'

Response：

{
  "ResponseMetadata": {
    "RequestId": "6163f1079c03952acff2b5ba4312fdb8",
    "Action": "GetAsset",
    "Version": "2024-01-01"
  },
  "Result": {
    "Id": "asset-xxx-yqveg",
    "AssetType": "Image",
    "Name": "user_123_portrait",
    "Status": "Active"
  }
}

Status 说明：

Status	说明
Processing	处理中，继续轮询。
Active	素材可用于 Seedance 视频生成。
Failed	素材创建失败，响应可能包含 ErrorMessage。

常见错误：

HTTP	Code	Message	说明
400	InvalidParameter	Id is required	未传 Id。
404	AssetNotFound	asset not found	asset 不存在或不属于当前账号。
409	AssetUnavailable	asset unavailable, please upload again: …	当前素材不可用，需要重新创建。

3.10 Seedance 生成中引用真人素材

当 GetAsset 返回 Active 后，可以在 Seedance 请求中使用：

{
  "model": "seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "使用 @image1 中的真人资产生成一段视频。人物面向镜头自然微笑，保持人物身份、发型和服装一致。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "asset://asset-xxx-xxx"
      },
      "role": "reference_image"
    }
  ]
}

3.11 完整流程示例

export ASSET_ENDPOINT="https://api.highwayapi.ai/v3/bytedance/ark"
export PLATFORM_API_KEY="<KEY>"
export CALLBACK_URL="https://your-app.example.com/liveness/done"

# Step 1: create liveness session
curl -sS -X POST "${ASSET_ENDPOINT}?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{
    \"CallbackURL\": \"${CALLBACK_URL}\"
  }"

# Step 2: open Result.H5Link in browser and finish liveness within 120 seconds.

# Step 3: exchange token for GroupId
curl -sS -X POST "${ASSET_ENDPOINT}?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "BytedToken": "<BYTED_TOKEN>"
  }'

# Step 4: create asset
curl -sS -X POST "${ASSET_ENDPOINT}?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "<GROUP_ID>",
    "URL": "https://your-cdn.example.com/portraits/user123.jpg",
    "AssetType": "Image",
    "Name": "user_123_portrait"
  }'

# Step 5: poll asset status
curl -sS -X POST "${ASSET_ENDPOINT}?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer ${PLATFORM_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "Id": "<ASSET_ID>"
  }'

3.12 排障清单

现象	优先检查
SessionExpired	用户是否在 120 秒内完成 H5 真人验证并调用 GetVisualValidateResult。
SessionNotFound	API Key 是否属于同一账号；BytedToken 是否复制正确。
AssetGroupNotFound	GroupId 是否来自当前 API Key 的 GetVisualValidateResult 响应。
图片上传失败	图片 URL 是否公网可下载；图片内容是否为完成真人验证的同一真人。
asset not ready	GetAsset 是否已经返回 Active。
带 asset 生成失败	asset 是否属于当前账号，且状态是否为 Active。

四、素材引用总览

4.1 两种素材 API 对比

维度	虚拟人像素材 API	真人素材 API
调用入口	/v3/synthetic/bytedance/ark	/v3/bytedance/ark
前置条件	无，直接 CreateAsset	需先完成 H5 真人验证，获取 GroupId
支持素材类型	Image、Video、Audio	仅 Image
CreateAsset 幂等维度	URL + AssetType + Name	GroupId + URL + AssetType + Name
CreateAsset 额外字段	ProjectName（可选，忽略）	GroupId（必填）
独有 Action	无	CreateVisualValidateSession、GetVisualValidateResult
引用方式	asset://<Id>	asset://<Id>

4.2 完整流程对比

虚拟人像素材流程：

CreateAsset（传入 URL、AssetType、Name）
GetAsset 轮询至 Status=Active
在 Seedance 生成请求中使用 asset://<Id> 引用

真人素材流程：

CreateVisualValidateSession（传入 CallbackURL）→ 获取 H5Link 和 BytedToken
用户在 H5 页面完成真人验证（120 秒内）
GetVisualValidateResult（传入 BytedToken）→ 获取 GroupId
CreateAsset（传入 GroupId、URL、AssetType、Name）
GetAsset 轮询至 Status=Active
在 Seedance 生成请求中使用 asset://<Id> 引用

Veo 3.1 Fast 首尾帧视频生成

VIDU Q2 Pro Fast 参考生视频

API 基础

大语言

图像

视频

音频

Seedance 2.0 原厂协议

一、视频生成 API

1.1 调用方式

1.2 支持模型

1.3 请求头

1.4 请求体

1.5 REST API 示例

1.6 SDK 示例

二、虚拟人像素材 API

2.1 适用范围

2.2 调用方式

2.3 鉴权

2.4 支持 Action

2.5 通用响应结构

2.6 创建资产 (CreateAsset)

2.7 查询资产状态 (GetAsset)

2.8 Seedance 生成中引用虚拟人像素材

2.9 排障清单

三、真人素材 API

3.1 适用范围

3.2 调用方式

3.3 鉴权

3.4 支持 Action

3.5 通用响应结构

3.6 创建 H5 真人验证会话 (CreateVisualValidateSession)

3.7 获取验证结果 (GetVisualValidateResult)

3.8 创建资产 (CreateAsset)

3.9 查询资产状态 (GetAsset)

3.10 Seedance 生成中引用真人素材

3.11 完整流程示例

3.12 排障清单

四、素材引用总览

4.1 两种素材 API 对比

4.2 完整流程对比

​一、视频生成 API

​1.1 调用方式

​1.2 支持模型

​1.3 请求头

​1.4 请求体

​1.5 REST API 示例

​1.6 SDK 示例

​二、虚拟人像素材 API

​2.1 适用范围

​2.2 调用方式

​2.3 鉴权

​2.4 支持 Action

​2.5 通用响应结构

​2.6 创建资产 (CreateAsset)

​2.7 查询资产状态 (GetAsset)

​2.8 Seedance 生成中引用虚拟人像素材

​2.9 排障清单

​三、真人素材 API

​3.1 适用范围

​3.2 调用方式

​3.3 鉴权

​3.4 支持 Action

​3.5 通用响应结构

​3.6 创建 H5 真人验证会话 (CreateVisualValidateSession)

​3.7 获取验证结果 (GetVisualValidateResult)

​3.8 创建资产 (CreateAsset)

​3.9 查询资产状态 (GetAsset)

​3.10 Seedance 生成中引用真人素材

​3.11 完整流程示例

​3.12 排障清单

​四、素材引用总览

​4.1 两种素材 API 对比

​4.2 完整流程对比

一、视频生成 API

1.1 调用方式

1.2 支持模型

1.3 请求头

1.4 请求体

1.5 REST API 示例

1.6 SDK 示例

二、虚拟人像素材 API

2.1 适用范围

2.2 调用方式

2.3 鉴权

2.4 支持 Action

2.5 通用响应结构

2.6 创建资产 (CreateAsset)

2.7 查询资产状态 (GetAsset)

2.8 Seedance 生成中引用虚拟人像素材

2.9 排障清单

三、真人素材 API

3.1 适用范围

3.2 调用方式

3.3 鉴权

3.4 支持 Action

3.5 通用响应结构

3.6 创建 H5 真人验证会话 (CreateVisualValidateSession)

3.7 获取验证结果 (GetVisualValidateResult)

3.8 创建资产 (CreateAsset)

3.9 查询资产状态 (GetAsset)

3.10 Seedance 生成中引用真人素材

3.11 完整流程示例

3.12 排障清单

四、素材引用总览

4.1 两种素材 API 对比

4.2 完整流程对比