跳至主要內容

Seedance 真人素材

Seedance 真人素材

真人素材用于在 Seedance 视频中稳定引用同一位真人。完整流程是：完成真人认证、取得人物组 ID、创建并等待素材生效，最后在视频内容中传入 asset://素材ID。

所有请求只使用 OhMyToken API Key。不要传入其他访问凭据；渠道凭据由 OhMyToken 在服务端保管并完成认证，不会返回给调用方。

支持以下两种客户端认证方式：

  • curl 或普通 HTTP 客户端：使用 Authorization: Bearer sk-...。
  • 火山引擎 Go SDK：把同一个 OhMyToken API Key 同时填写为 AK 和 SK。

通用调用格式

POST https://ohmytoken.cn/seedance-gateway?Action={ACTION}&Version=2024-01-01
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=CreateAssetGroup&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Name":"示例人物","Description":"真人素材组","GroupType":"AIGC"}'

ProjectName 由网关统一注入，客户端传入的同名字段会被覆盖。真人素材和使用 asset:// 的视频生成会固定到同一个上游项目与渠道。

火山引擎 Go SDK

SDK 的 Endpoint 指向 OhMyToken，AK 和 SK 都填写同一个 OhMyToken API Key：

package main

import (
    "fmt"
    "os"

    "github.com/volcengine/volcengine-go-sdk/volcengine"
    "github.com/volcengine/volcengine-go-sdk/volcengine/credentials"
    "github.com/volcengine/volcengine-go-sdk/volcengine/session"
    "github.com/volcengine/volcengine-go-sdk/volcengine/universal"
)

func main() {
    apiKey := os.Getenv("OHMYTOKEN_API_KEY")
    config := volcengine.NewConfig().
        WithRegion("cn-beijing").
        WithCredentials(credentials.NewStaticCredentials(apiKey, apiKey, "")).
        WithEndpoint("https://ohmytoken.cn/seedance-gateway")
    config.DisableRestProtocolURICleaning = volcengine.Bool(true)

    client := universal.New(session.New(config))
    request := universal.RequestUniversal{
        ServiceName: "ark",
        Action:      "ListAssetGroups",
        Version:     "2024-01-01",
        HttpMethod:  universal.POST,
        ContentType: universal.ApplicationJSON,
    }
    input := map[string]interface{}{
        "PageNumber": 1,
        "PageSize":   10,
        "SortBy":     "CreateTime",
        "SortOrder":  "Desc",
    }
    output, err := client.DoCall(request, &input)
    if err != nil {
        panic(err)
    }
    fmt.Println(output)
}

其他 Action 只需替换 Action 和 input；下文的 curl 请求体字段可直接作为 SDK 的 input。

1. 创建真人认证会话

Action=CreateVisualValidateSession

字段类型必填说明
CallbackURLstring是真人认证完成后跳转的 HTTPS 地址
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=CreateVisualValidateSession&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"CallbackURL":"https://example.com/seedance/callback"}'

在返回的 H5 地址完成认证。回调得到的 BytedToken 有效期约 30 分钟，应尽快查询结果。

2. 查询认证结果

Action=GetVisualValidateResult

字段类型必填说明
BytedTokenstring是认证回调返回的临时令牌
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=GetVisualValidateResult&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"BytedToken":"BYTE_TOKEN_FROM_CALLBACK"}'

认证成功后保存返回的 GroupId。一个人物组只应对应一位真人，后续素材应保持同一人物的面部一致性。

3. 创建人物组

已取得认证结果时通常直接使用返回的 GroupId。需要单独创建人物组时使用 Action=CreateAssetGroup。

字段类型必填说明
Namestring是人物组名称
Descriptionstring否人物组说明
GroupTypestring是真人生成场景填写 AIGC
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=CreateAssetGroup&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Name":"人物一","Description":"品牌短片人物","GroupType":"AIGC"}'

4. 创建真人素材

Action=CreateAsset

字段类型必填说明
GroupIdstring是当前项目内的人物组 ID
URLstring是上游可访问的素材图片 URL
AssetTypestring是图片填写 Image
Namestring是素材名称
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=CreateAsset&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "GroupId":"group-example",
    "URL":"https://example.com/person-front.jpg",
    "AssetType":"Image",
    "Name":"人物正面照"
  }'

保存返回的素材 ID。创建成功后素材仍可能处于 Processing，必须查询到 Active 后再用于生成。

5. 查询和列出素材

查询单个素材使用 Action=GetAsset：

curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=GetAsset&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Id":"asset-example"}'

列出素材使用 Action=ListAssets：

字段类型必填说明
Filter.GroupIdsstring[]否按人物组 ID 过滤
Filter.GroupTypestring否通常为 AIGC
Filter.Statusesstring[]否例如 Active、Processing、Failed
Filter.Namestring否按名称过滤
PageNumberinteger否页码，从 1 开始
PageSizeinteger否每页数量
SortBystring否例如 CreateTime
SortOrderstring否Asc 或 Desc
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=ListAssets&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "Filter":{"GroupIds":["group-example"],"GroupType":"AIGC","Statuses":["Active","Processing"]},
    "PageNumber":1,"PageSize":10,"SortBy":"CreateTime","SortOrder":"Desc"
  }'

响应中的临时 URL 通常约 12 小时失效。视频生成应使用永久标识 asset://素材ID，不要保存临时 URL 作为长期引用。

6. 查询和列出人物组

查询单个人物组使用 Action=GetAssetGroup，请求体为 {"Id":"group-example"}。

curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=ListAssetGroups&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "Filter":{"Name":"人物","GroupType":"AIGC"},
    "PageNumber":1,"PageSize":10,"SortBy":"CreateTime","SortOrder":"Desc"
  }'

ListAssetGroups 的过滤与分页字段和 ListAssets 相同，但 Filter 使用 Name、GroupType。

7. 更新名称和说明

更新素材使用 Action=UpdateAsset：

curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=UpdateAsset&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Id":"asset-example","Name":"人物正面照新版"}'

更新人物组使用 Action=UpdateAssetGroup：

curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=UpdateAssetGroup&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Id":"group-example","Name":"品牌人物一","Description":"2026 秋季短片"}'

8. 删除素材和人物组

删除操作不可恢复。删除素材使用 Action=DeleteAsset，删除人物组使用 Action=DeleteAssetGroup。

curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=DeleteAsset&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Id":"asset-example"}'
curl --request POST \
  'https://ohmytoken.cn/seedance-gateway?Action=DeleteAssetGroup&Version=2024-01-01' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"Id":"group-example"}'

删除人物组后，该组及其关联素材将按上游规则处理。

9. 使用真人素材生成视频

素材状态为 Active 后，在 Seedance 原生接口的 image_url.url 中传入 asset://素材ID。普通公网参考图仍可与真人素材同时使用，提示词可按内容顺序使用“图片1”“图片2”指代素材。

curl --request POST 'https://ohmytoken.cn/api/v3/contents/generations/tasks' \
  --header "Authorization: Bearer ${OHMYTOKEN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "model":"doubao-seedance-2.0",
    "content":[
      {"type":"text","text":"保持图片1中真人的身份和面部特征，让她走进图片2的咖啡馆并向镜头挥手"},
      {"type":"image_url","image_url":{"url":"asset://asset-example"}},
      {"type":"image_url","image_url":{"url":"https://example.com/cafe.jpg"}}
    ],
    "ratio":"16:9",
    "duration":8,
    "resolution":"720p",
    "generate_audio":true
  }'

任务创建和查询响应参见 Seedance 原生接口。包含 asset:// 的请求会固定到真人素材网关所使用的上游渠道。

最近更新:
贡献者: Miracle Ron
OhMyToken 使用文档