真人认证接口

要在视频中使用真实人物形象，本人必须先通过活体认证（刷脸），认证通过后系统自动创建一个 LivenessFace 素材组，此后即可向该组上传这位真人的照片并在视频生成中引用。整个流程全 API 化，无需人工审核介入。

该流程用于防止深度伪造：只有完成刷脸的本人形象才能被用于生成，未经认证的真实人脸图片会被内容审核拒绝。

鉴权方式

真人认证与素材库共用同一入口，支持 API Key 和火山官方 AK/SK 两种鉴权方式。两种方式访问同一份账号素材数据，并受对应 API Key 的额度、状态、有效期和访问策略约束。

API Key（Bearer）

POST https://api.looprouter.com/api/v3/assets?Action=<操作名>&Version=2024-01-01
Authorization: Bearer sk-...

火山官方 AK/SK（HMAC-SHA256）

使用 API Key 所绑定的 AK/SK，按照火山官方 HMAC-SHA256 方式签名。已有火山客户端只需将 Endpoint 替换为 https://api.looprouter.com，并使用 LoopRouter API Key 页面生成的 AK/SK；Action、Version、请求体和响应解析保持不变。火山签名请求使用根路径 /，Service 为 ark，Region 推荐 cn-beijing。下面示例使用火山官方 Go SDK 发起真人认证会话：

package main

import (
  "bytes"
  "io"
  "net/http"
  "os"

  "github.com/volcengine/volc-sdk-golang/base"
)

func main() {
  body := []byte(`{"Name":"主播小李","Description":"直播切片项目"}`)
  req, err := http.NewRequest(
    http.MethodPost,
    "https://api.looprouter.com/?Action=CreateVisualValidateSession&Version=2024-01-01",
    bytes.NewReader(body),
  )
  if err != nil {
    panic(err)
  }
  req.Header.Set("Content-Type", "application/json")

  credentials := base.Credentials{
    AccessKeyID:     os.Getenv("LOOPROUTER_AK"),
    SecretAccessKey: os.Getenv("LOOPROUTER_SK"),
    Region:          "cn-beijing",
    Service:         "ark",
  }
  req = credentials.Sign(req)

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()
  io.Copy(os.Stdout, resp.Body)
}

AK/SK 可用于 CreateVisualValidateSession、GetVisualValidateResult 及其他 JSON 素材 Action。后续视频生成接口仍使用 API Key；本地文件 multipart/form-data 上传也继续使用 API Key。

认证流程

发起认证会话 — CreateVisualValidateSession

curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "主播小李", "Description": "直播切片项目"}'

响应：

{
  "ResponseMetadata": { "RequestId": "...", "Action": "CreateVisualValidateSession", "Version": "2024-01-01", "Service": "ark" },
  "Result": {
    "BytedToken": "a1b2c3d4e5f6a7b8",
    "H5Link": "https://api.looprouter.com/api/portrait/visual-validation/go/a1b2c3d4e5f6a7b8",
    "ExpireTime": 1752941700000
  }
}

字段	说明
`BytedToken`	认证会话令牌，用于后续查询结果
`H5Link`	刷脸页面链接，在手机浏览器中打开（可将其生成二维码给被认证人扫码）
`ExpireTime`	会话过期时间（毫秒时间戳），过期需重新发起

被认证人完成 H5 刷脸

将 H5Link 发给需要认证的本人，用手机打开并按提示完成人脸活体检测。会话有效期约 15 分钟。

查询认证结果 — GetVisualValidateResult

curl -X POST "https://api.looprouter.com/api/v3/assets?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken": "a1b2c3d4e5f6a7b8"}'

三种结果：认证通过 — HTTP 200，返回真人素材组 ID：

{ "Result": { "Status": "passed", "GroupId": "group-20260709185838-dcnvd" } }

尚未完成 — HTTP 404，Error.Code 为 NotFound.VisualValidateResult。这不是异常，表示对方还没刷完脸，继续轮询即可（建议 3–5 秒一次）。失败 / 过期 — HTTP 200，Result.Status 为 failed 或 expired，失败时附带 ResultCode / ResultMessage。

向真人素材组上传照片 — CreateAsset

curl -X POST "https://api.looprouter.com/api/v3/assets?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-20260709185838-dcnvd",
    "Name": "小李-正面照",
    "URL": "https://example.com/xiaoli.jpg"
  }'

照片必须是已认证本人的清晰照片；上传其他人的照片会在内容审核阶段失败。随后用 GetAsset 轮询到 Status: "Active"。

在视频生成中引用真人素材

curl -X POST "https://api.looprouter.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $LOOPROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "图片1中的人物坐在书桌前，对镜头介绍产品：\"大家好，今天给大家带来一款新品\""},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260709190143-ntwhb"}, "role": "reference_image"}
    ],
    "resolution": "720p",
    "duration": 8
  }'

Python 完整示例

import time
import requests

BASE = "https://api.looprouter.com/api/v3/assets"
HEADERS = {"Authorization": "Bearer sk-你的APIKey", "Accept-Encoding": "identity"}

def action(name, body):
    resp = requests.post(f"{BASE}?Action={name}&Version=2024-01-01", headers=HEADERS, json=body)
    return resp.status_code, resp.json()

# 1. 发起认证
_, data = action("CreateVisualValidateSession", {"Name": "主播小李"})
token = data["Result"]["BytedToken"]
print("请用手机打开完成刷脸:", data["Result"]["H5Link"])

# 2. 轮询认证结果（404 = 还没刷完，继续等）
while True:
    code, data = action("GetVisualValidateResult", {"BytedToken": token})
    if code == 404:
        time.sleep(5)
        continue
    status = data["Result"]["Status"]
    if status == "passed":
        group_id = data["Result"]["GroupId"]
        print("认证通过，素材组:", group_id)
        break
    raise SystemExit(f"认证未通过: {data['Result']}")

# 3. 上传真人照片并等待 Active
_, data = action("CreateAsset", {
    "GroupId": group_id,
    "Name": "小李-正面照",
    "URL": "https://example.com/xiaoli.jpg",
})
asset_id = data["Result"]["Id"]
while True:
    _, data = action("GetAsset", {"Id": asset_id})
    if data["Result"]["Status"] in ("Active", "Failed"):
        break
    time.sleep(3)
print("素材状态:", data["Result"]["Status"], "→ 生成请求中引用 asset://" + asset_id)

注意事项

BytedToken 与素材组、素材 ID 一样属于敏感凭据，请勿泄露。
认证会话约 15 分钟过期，请在发起后尽快完成刷脸；过期后重新调用 CreateVisualValidateSession 即可。
一次认证对应一个真人素材组；同一账号可为多位真人分别发起认证，各自维护素材组。

生成效果建议：同一真人上传「正面全身照 + 自然表情面部特写」两张素材并同时引用；提示词中用「图片1」「图片2」指代，台词放在双引号内可获得更好的口播效果。

错误码

HTTP	Code	说明
400	`MissingParameter`	缺少 `BytedToken` / `GroupId` / `URL` 等必填字段
404	`NotFound.VisualValidateResult`	认证尚未完成（轮询中的正常状态）
404	`NotFound`	会话/素材组不存在或不属于当前账号
429	`RateLimitExceeded`	操作过于频繁，稍后重试
503	`NoAvailableAssetChannel`	当前账号的素材库服务暂未就绪，请联系我们开通

素材库 API

素材组与素材的完整管理接口

素材引用实战

从上传到生成的端到端示例

视频生成 API

生成参数详解

产品基础

视频模型

图片模型

鉴权方式

API Key（Bearer）

火山官方 AK/SK（HMAC-SHA256）

认证流程

Python 完整示例

注意事项

错误码

相关文档

素材库 API

素材引用实战

视频生成 API

​鉴权方式

​API Key（Bearer）

​火山官方 AK/SK（HMAC-SHA256）

​认证流程

​Python 完整示例

​注意事项

​错误码

​相关文档

素材库 API

素材引用实战

视频生成 API

鉴权方式

API Key（Bearer）

火山官方 AK/SK（HMAC-SHA256）

认证流程

Python 完整示例

注意事项

错误码

相关文档