[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-nav-zh":3,"docs-zh-models\u002Fvideo\u002Fliveness-verification":180},[4,26,43,105,155,172,176],{"title":5,"path":6,"stem":7,"children":8,"page":25},"快速开始","\u002Fgetting-started","1.getting-started",[9,13,17,21],{"title":10,"path":11,"stem":12},"首次调用千木 API","\u002Fgetting-started\u002Fquick-start","1.getting-started\u002F1.quick-start",{"title":14,"path":15,"stem":16},"模型选择","\u002Fgetting-started\u002Fmodel-selection","1.getting-started\u002F2.model-selection",{"title":18,"path":19,"stem":20},"限流","\u002Fgetting-started\u002Frate-limits","1.getting-started\u002F3.rate-limits",{"title":22,"path":23,"stem":24},"常见问题","\u002Fgetting-started\u002Ffaq","1.getting-started\u002F4.faq",false,{"title":27,"path":28,"stem":29,"children":30,"page":25},"产品计费","\u002Fbilling","2.billing",[31,35,39],{"title":32,"path":33,"stem":34},"计费说明","\u002Fbilling\u002Foverview","2.billing\u002F1.overview",{"title":36,"path":37,"stem":38},"在线充值","\u002Fbilling\u002Frecharge","2.billing\u002F2.recharge",{"title":40,"path":41,"stem":42},"账单、用量与导出","\u002Fbilling\u002Fusage-export","2.billing\u002F3.usage-export",{"title":44,"path":45,"stem":46,"children":47,"page":25},"Coding Plan","\u002Fcoding-plan","3.coding-plan",[48,52,56,60,67,102],{"title":49,"path":50,"stem":51},"Coding Plan 概述","\u002Fcoding-plan\u002Foverview","3.coding-plan\u002F1.overview",{"title":53,"path":54,"stem":55},"快速接入","\u002Fcoding-plan\u002Fquick-start","3.coding-plan\u002F2.quick-start",{"title":57,"path":58,"stem":59},"使用须知","\u002Fcoding-plan\u002Fusage-notes","3.coding-plan\u002F3.usage-notes",{"title":61,"path":62,"stem":63,"children":64},"个人版","\u002Fcoding-plan\u002Fpersonal","3.coding-plan\u002F4.personal\u002Findex",[65],{"title":66,"path":62,"stem":63},"价格和权益",{"title":68,"path":69,"stem":70,"children":71,"page":-1},"开发指南","\u002Fcoding-plan\u002Fguide","3.coding-plan\u002F5.guide\u002Findex",[72,74,78,82,86,90,94,98],{"title":73,"path":69,"stem":70},"端点与协议",{"title":75,"path":76,"stem":77},"Claude Code","\u002Fcoding-plan\u002Fguide\u002Fclaude-code","3.coding-plan\u002F5.guide\u002F1.claude-code",{"title":79,"path":80,"stem":81},"OpenCode","\u002Fcoding-plan\u002Fguide\u002Fopencode","3.coding-plan\u002F5.guide\u002F2.opencode",{"title":83,"path":84,"stem":85},"Cursor","\u002Fcoding-plan\u002Fguide\u002Fcursor","3.coding-plan\u002F5.guide\u002F3.cursor",{"title":87,"path":88,"stem":89},"Codex","\u002Fcoding-plan\u002Fguide\u002Fcodex","3.coding-plan\u002F5.guide\u002F4.codex",{"title":91,"path":92,"stem":93},"ZCode","\u002Fcoding-plan\u002Fguide\u002Fzcode","3.coding-plan\u002F5.guide\u002F5.zcode",{"title":95,"path":96,"stem":97},"TRAE","\u002Fcoding-plan\u002Fguide\u002Ftrae","3.coding-plan\u002F5.guide\u002F6.trae",{"title":99,"path":100,"stem":101},"CodeBuddy","\u002Fcoding-plan\u002Fguide\u002Fcodebuddy","3.coding-plan\u002F5.guide\u002F7.codebuddy",{"title":22,"path":103,"stem":104},"\u002Fcoding-plan\u002Ffaq","3.coding-plan\u002F6.faq",{"title":106,"path":107,"stem":108,"children":109,"page":25},"模型接口","\u002Fmodels","4.models",[110,143],{"title":111,"path":112,"stem":113,"children":114,"page":25},"文本生成API","\u002Fmodels\u002Fchat","4.models\u002F1.chat",[115,119,123,127,131,135,139],{"title":116,"path":117,"stem":118},"概述","\u002Fmodels\u002Fchat\u002Foverview","4.models\u002F1.chat\u002F1.overview",{"title":120,"path":121,"stem":122},"OpenAI 兼容接口","\u002Fmodels\u002Fchat\u002Fopenai","4.models\u002F1.chat\u002F2.openai",{"title":124,"path":125,"stem":126},"Anthropic 兼容","\u002Fmodels\u002Fchat\u002Fanthropic","4.models\u002F1.chat\u002F3.anthropic",{"title":128,"path":129,"stem":130},"Volcengine 兼容","\u002Fmodels\u002Fchat\u002Fvolcengine","4.models\u002F1.chat\u002F4.volcengine",{"title":132,"path":133,"stem":134},"智谱兼容","\u002Fmodels\u002Fchat\u002Fzhipu","4.models\u002F1.chat\u002F5.zhipu",{"title":136,"path":137,"stem":138},"SilvaMux 统一入口","\u002Fmodels\u002Fchat\u002Funified","4.models\u002F1.chat\u002F6.unified",{"title":140,"path":141,"stem":142},"多模态输入","\u002Fmodels\u002Fchat\u002Fmultimodal","4.models\u002F1.chat\u002F7.multimodal",{"title":144,"path":145,"stem":146,"children":147,"page":25},"图片生成API","\u002Fmodels\u002Fimages","4.models\u002F2.images",[148,151],{"title":116,"path":149,"stem":150},"\u002Fmodels\u002Fimages\u002Foverview","4.models\u002F2.images\u002F1.overview",{"title":152,"path":153,"stem":154},"图片生成接口","\u002Fmodels\u002Fimages\u002Fgeneration","4.models\u002F2.images\u002F2.generation",{"title":156,"path":157,"stem":158,"children":159,"page":25},"用量与余额API","\u002Fusage-and-balance","5.usage-and-balance",[160,164,168],{"title":161,"path":162,"stem":163},"查询余额","\u002Fusage-and-balance\u002Fbalance","5.usage-and-balance\u002F1.balance",{"title":165,"path":166,"stem":167},"查询用量","\u002Fusage-and-balance\u002Fusage","5.usage-and-balance\u002F2.usage",{"title":169,"path":170,"stem":171},"查询单次请求消耗","\u002Fusage-and-balance\u002Frequest-usage","5.usage-and-balance\u002F3.request-usage",{"title":173,"path":174,"stem":175},"错误码参考","\u002Ferrors","6.errors",{"title":177,"path":178,"stem":179},"开始使用 SilvaMux","\u002F","index",{"id":181,"title":182,"body":183,"description":1703,"extension":1704,"meta":1705,"navigation":25,"path":1706,"rawbody":1707,"requiredFlags":1708,"seo":1709,"stem":1710,"__hash__":1711},"docs\u002F4.models\u002F3.video\u002F4.liveness-verification.md","人像认证（真人活体认证）",{"type":184,"value":185,"toc":1686},"minimark",[186,190,204,214,228,232,257,335,338,476,480,486,489,540,590,611,614,741,779,784,788,797,834,840,844,850,852,877,899,901,978,988,1028,1032,1038,1040,1110,1168,1170,1238,1255,1259,1264,1270,1275,1297,1301,1307,1350,1354,1360,1365,1368,1380,1482,1499,1502,1611,1614,1658,1661,1682],[187,188,182],"h1",{"id":189},"人像认证真人活体认证",[191,192,193,194,198,199,203],"p",{},"SilvaMux 提供与火山引擎一致的「真人认证」人脸活体识别接口。客户可以拉起火山 H5 活体认证页面，完成本人认证后把正脸素材入库为",[195,196,197],"strong",{},"真人素材（LivenessFace）","，再通过 ",[200,201,202],"code",{},"asset:\u002F\u002F\u003CId>"," 在视频生成中引用，构成私域真人人像库的完整闭环：",[205,206,211],"pre",{"className":207,"code":209,"language":210},[208],"language-text","拉起活体认证 H5 → 用户完成认证 → 回调 → 获取真人素材组 → 上传真人素材 → 生成视频\n","text",[200,212,209],{"__ignoreMap":213},"",[215,216,217],"blockquote",{},[191,218,219,220,227],{},"接口行为与火山引擎「管理私域素材库」一致（",[221,222,226],"a",{"href":223,"rel":224},"https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F82379\u002F2333587?lang=zh",[225],"nofollow","拉起真人认证 H5（CreateVisualValidateSession）","），只是 Endpoint 指向本平台、鉴权凭证使用平台签发的 AK\u002FSK。",[229,230,231],"h2",{"id":231},"接入准备",[233,234,235,243,254],"ol",{},[236,237,238,239,242],"li",{},"控制台 → 凭据管理 → 创建 ",[195,240,241],{},"Volcengine 兼容 (AK\u002FSK)"," 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。",[236,244,245,246,249,250,253],{},"AK\u002FSK 绑定组织，项目通过 ",[200,247,248],{},"ProjectName"," 字段指定（留空或填 ",[200,251,252],{},"default"," 使用默认项目）。",[236,255,256],{},"使用火山引擎官方 SDK 或自定义 V4 签名，请求发送到本平台：",[258,259,260,273],"table",{},[261,262,263],"thead",{},[264,265,266,270],"tr",{},[267,268,269],"th",{},"项",[267,271,272],{},"值",[274,275,276,287,297,307,317,325],"tbody",{},[264,277,278,282],{},[279,280,281],"td",{},"Endpoint",[279,283,284],{},[200,285,286],{},"https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fark",[264,288,289,292],{},[279,290,291],{},"Region",[279,293,294],{},[200,295,296],{},"cn-beijing",[264,298,299,302],{},[279,300,301],{},"Service",[279,303,304],{},[200,305,306],{},"ark",[264,308,309,312],{},[279,310,311],{},"Version",[279,313,314],{},[200,315,316],{},"2024-01-01",[264,318,319,322],{},[279,320,321],{},"鉴权",[279,323,324],{},"火山 V4 签名，使用平台签发的 AK\u002FSK",[264,326,327,330],{},[279,328,329],{},"调用方式",[279,331,332],{},[200,333,334],{},"POST \u002Fapi\u002Fark?Action=\u003CAction>&Version=2024-01-01",[229,336,337],{"id":337},"整体流程",[258,339,340,356],{},[261,341,342],{},[264,343,344,347,350,353],{},[267,345,346],{},"步骤",[267,348,349],{},"动作",[267,351,352],{},"接口",[267,354,355],{},"结果",[274,357,358,381,405,425,456],{},[264,359,360,363,366,371],{},[279,361,362],{},"①",[279,364,365],{},"发起真人认证",[279,367,368],{},[200,369,370],{},"CreateVisualValidateSession",[279,372,373,376,377,380],{},[200,374,375],{},"H5Link"," + ",[200,378,379],{},"BytedToken","（会话 id）",[264,382,383,386,389,392],{},[279,384,385],{},"②",[279,387,388],{},"用户打开 H5 完成活体认证",[279,390,391],{},"浏览器跳转，平台回调",[279,393,394,395,398,399,376,402],{},"自动跳回你的 ",[200,396,397],{},"CallbackURL","，带 ",[200,400,401],{},"bytedToken",[200,403,404],{},"resultCode",[264,406,407,410,413,418],{},[279,408,409],{},"③",[279,411,412],{},"确认认证结果并获取素材组",[279,414,415],{},[200,416,417],{},"GetVisualValidateResult",[279,419,420,421,424],{},"生成并返回 ",[200,422,423],{},"GroupId","（LivenessFace 真人素材组，一次性）",[264,426,427,430,433,442],{},[279,428,429],{},"④",[279,431,432],{},"上传真人素材",[279,434,435,438,439,441],{},[200,436,437],{},"CreateAsset","（指向 ③ 的 ",[200,440,423],{},"）",[279,443,444,445,448,449,452,453],{},"返回真实上游素材 ",[200,446,447],{},"Id","，轮询 ",[200,450,451],{},"GetAsset"," 至 ",[200,454,455],{},"Active",[264,457,458,461,464,467],{},[279,459,460],{},"⑤",[279,462,463],{},"生成视频",[279,465,466],{},"视频生成接口",[279,468,469,472,473,475],{},[200,470,471],{},"content"," 中用 ",[200,474,202],{}," 引用",[229,477,479],{"id":478},"创建认证会话-createvisualvalidatesession","① 创建认证会话 CreateVisualValidateSession",[205,481,484],{"className":482,"code":483,"language":210},[208],"POST \u002Fapi\u002Fark?Action=CreateVisualValidateSession&Version=2024-01-01\n",[200,485,483],{"__ignoreMap":213},[191,487,488],{},"请求体：",[258,490,491,504],{},[261,492,493],{},[264,494,495,498,501],{},[267,496,497],{},"字段",[267,499,500],{},"必填",[267,502,503],{},"说明",[274,505,506,525],{},[264,507,508,512,515],{},[279,509,510],{},[200,511,397],{},[279,513,514],{},"是",[279,516,517,518,178,521,524],{},"认证完成后接收结果的回调地址，必须是 ",[200,519,520],{},"http",[200,522,523],{},"https"," URL",[264,526,527,531,534],{},[279,528,529],{},[200,530,248],{},[279,532,533],{},"否",[279,535,536,537,539],{},"项目名；留空或 ",[200,538,252],{}," 使用默认项目",[205,541,545],{"className":542,"code":543,"language":544,"meta":213,"style":213},"language-json shiki shiki-themes github-light github-dark","{\n  \"CallbackURL\": \"https:\u002F\u002Fyour-host.example\u002Fcallback\",\n  \"ProjectName\": \"default\"\n}\n","json",[200,546,547,556,573,584],{"__ignoreMap":213},[548,549,552],"span",{"class":550,"line":551},"line",1,[548,553,555],{"class":554},"sVt8B","{\n",[548,557,559,563,566,570],{"class":550,"line":558},2,[548,560,562],{"class":561},"sj4cs","  \"CallbackURL\"",[548,564,565],{"class":554},": ",[548,567,569],{"class":568},"sZZnC","\"https:\u002F\u002Fyour-host.example\u002Fcallback\"",[548,571,572],{"class":554},",\n",[548,574,576,579,581],{"class":550,"line":575},3,[548,577,578],{"class":561},"  \"ProjectName\"",[548,580,565],{"class":554},[548,582,583],{"class":568},"\"default\"\n",[548,585,587],{"class":550,"line":586},4,[548,588,589],{"class":554},"}\n",[215,591,592],{},[191,593,594,595,598,599,598,602,605,606,610],{},"请求使用平台签发的 AK\u002FSK 做火山 V4 签名（",[200,596,597],{},"Service=ark","、",[200,600,601],{},"Region=cn-beijing",[200,603,604],{},"Version=2024-01-01","），具体签名方式见",[221,607,609],{"href":608},"\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Fassets","素材管理","接入说明。",[191,612,613],{},"响应：",[205,615,617],{"className":542,"code":616,"language":544,"meta":213,"style":213},"{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"3f2f8b4d1a6e4c5b9a7d0e2f1c3b4a5d\",\n    \"Action\": \"CreateVisualValidateSession\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"H5Link\": \"https:\u002F\u002F...（火山 H5 活体认证页面）\",\n    \"BytedToken\": \"VVS-01JXXXXXXXXXXXXXX\"\n  }\n}\n",[200,618,619,623,631,643,655,668,681,692,698,706,719,730,736],{"__ignoreMap":213},[548,620,621],{"class":550,"line":551},[548,622,555],{"class":554},[548,624,625,628],{"class":550,"line":558},[548,626,627],{"class":561},"  \"ResponseMetadata\"",[548,629,630],{"class":554},": {\n",[548,632,633,636,638,641],{"class":550,"line":575},[548,634,635],{"class":561},"    \"RequestId\"",[548,637,565],{"class":554},[548,639,640],{"class":568},"\"3f2f8b4d1a6e4c5b9a7d0e2f1c3b4a5d\"",[548,642,572],{"class":554},[548,644,645,648,650,653],{"class":550,"line":586},[548,646,647],{"class":561},"    \"Action\"",[548,649,565],{"class":554},[548,651,652],{"class":568},"\"CreateVisualValidateSession\"",[548,654,572],{"class":554},[548,656,658,661,663,666],{"class":550,"line":657},5,[548,659,660],{"class":561},"    \"Version\"",[548,662,565],{"class":554},[548,664,665],{"class":568},"\"2024-01-01\"",[548,667,572],{"class":554},[548,669,671,674,676,679],{"class":550,"line":670},6,[548,672,673],{"class":561},"    \"Service\"",[548,675,565],{"class":554},[548,677,678],{"class":568},"\"ark\"",[548,680,572],{"class":554},[548,682,684,687,689],{"class":550,"line":683},7,[548,685,686],{"class":561},"    \"Region\"",[548,688,565],{"class":554},[548,690,691],{"class":568},"\"cn-beijing\"\n",[548,693,695],{"class":550,"line":694},8,[548,696,697],{"class":554},"  },\n",[548,699,701,704],{"class":550,"line":700},9,[548,702,703],{"class":561},"  \"Result\"",[548,705,630],{"class":554},[548,707,709,712,714,717],{"class":550,"line":708},10,[548,710,711],{"class":561},"    \"H5Link\"",[548,713,565],{"class":554},[548,715,716],{"class":568},"\"https:\u002F\u002F...（火山 H5 活体认证页面）\"",[548,718,572],{"class":554},[548,720,722,725,727],{"class":550,"line":721},11,[548,723,724],{"class":561},"    \"BytedToken\"",[548,726,565],{"class":554},[548,728,729],{"class":568},"\"VVS-01JXXXXXXXXXXXXXX\"\n",[548,731,733],{"class":550,"line":732},12,[548,734,735],{"class":554},"  }\n",[548,737,739],{"class":550,"line":738},13,[548,740,589],{"class":554},[258,742,743,751],{},[261,744,745],{},[264,746,747,749],{},[267,748,497],{},[267,750,503],{},[274,752,753,762],{},[264,754,755,759],{},[279,756,757],{},[200,758,375],{},[279,760,761],{},"让用户在浏览器（手机\u002FPC）打开的活体认证页面",[264,763,764,768],{},[279,765,766],{},[200,767,379],{},[279,769,770,773,774,776,777],{},[195,771,772],{},"平台会话 id","，后续 ",[200,775,417],{}," 使用它作为 ",[200,778,379],{},[215,780,781],{},[191,782,783],{},"H5 链接仅能使用一次，会话有效期 30 分钟。",[229,785,787],{"id":786},"认证回调","② 认证回调",[191,789,790,791,793,794,796],{},"用户打开 ",[200,792,375],{}," 完成眨眼\u002F转头等活体动作后，火山引擎把用户浏览器重定向到平台回调；平台记录认证结果后，用一个 HTML 页面把浏览器自动跳转到你提供的 ",[200,795,397],{},"，并附加参数：",[258,798,799,808],{},[261,800,801],{},[264,802,803,806],{},[267,804,805],{},"参数",[267,807,503],{},[274,809,810,822],{},[264,811,812,816],{},[279,813,814],{},[200,815,401],{},[279,817,818,819,821],{},"平台会话 id（与 ① 返回的 ",[200,820,379],{}," 相同）",[264,823,824,828],{},[279,825,826],{},[200,827,404],{},[279,829,830,833],{},[200,831,832],{},"10000"," 表示认证通过",[191,835,836,837,839],{},"你的回调服务可据此展示「认证结果」，随后调用 ",[200,838,417],{}," 正式获取素材组。",[229,841,843],{"id":842},"获取真人素材组-getvisualvalidateresult","③ 获取真人素材组 GetVisualValidateResult",[205,845,848],{"className":846,"code":847,"language":210},[208],"POST \u002Fapi\u002Fark?Action=GetVisualValidateResult&Version=2024-01-01\n",[200,849,847],{"__ignoreMap":213},[191,851,488],{},[258,853,854,864],{},[261,855,856],{},[264,857,858,860,862],{},[267,859,497],{},[267,861,500],{},[267,863,503],{},[274,865,866],{},[264,867,868,872,874],{},[279,869,870],{},[200,871,379],{},[279,873,514],{},[279,875,876],{},"① 返回的会话 id",[205,878,880],{"className":542,"code":879,"language":544,"meta":213,"style":213},"{\n  \"BytedToken\": \"VVS-01JXXXXXXXXXXXXXX\"\n}\n",[200,881,882,886,895],{"__ignoreMap":213},[548,883,884],{"class":550,"line":551},[548,885,555],{"class":554},[548,887,888,891,893],{"class":550,"line":558},[548,889,890],{"class":561},"  \"BytedToken\"",[548,892,565],{"class":554},[548,894,729],{"class":568},[548,896,897],{"class":550,"line":575},[548,898,589],{"class":554},[191,900,613],{},[205,902,904],{"className":542,"code":903,"language":544,"meta":213,"style":213},"{\n  \"ResponseMetadata\": { \"Action\": \"GetVisualValidateResult\", \"Version\": \"2024-01-01\", \"Service\": \"ark\", \"Region\": \"cn-beijing\" },\n  \"Result\": { \"GroupId\": \"group-01JXXXXXXXXXXXXXX\" }\n}\n",[200,905,906,910,957,974],{"__ignoreMap":213},[548,907,908],{"class":550,"line":551},[548,909,555],{"class":554},[548,911,912,914,917,920,922,925,928,931,933,935,937,940,942,944,946,949,951,954],{"class":550,"line":558},[548,913,627],{"class":561},[548,915,916],{"class":554},": { ",[548,918,919],{"class":561},"\"Action\"",[548,921,565],{"class":554},[548,923,924],{"class":568},"\"GetVisualValidateResult\"",[548,926,927],{"class":554},", ",[548,929,930],{"class":561},"\"Version\"",[548,932,565],{"class":554},[548,934,665],{"class":568},[548,936,927],{"class":554},[548,938,939],{"class":561},"\"Service\"",[548,941,565],{"class":554},[548,943,678],{"class":568},[548,945,927],{"class":554},[548,947,948],{"class":561},"\"Region\"",[548,950,565],{"class":554},[548,952,953],{"class":568},"\"cn-beijing\"",[548,955,956],{"class":554}," },\n",[548,958,959,961,963,966,968,971],{"class":550,"line":575},[548,960,703],{"class":561},[548,962,916],{"class":554},[548,964,965],{"class":561},"\"GroupId\"",[548,967,565],{"class":554},[548,969,970],{"class":568},"\"group-01JXXXXXXXXXXXXXX\"",[548,972,973],{"class":554}," }\n",[548,975,976],{"class":550,"line":586},[548,977,589],{"class":554},[191,979,980,981,984,985,987],{},"成功后平台会创建并返回一个 ",[195,982,983],{},"LivenessFace 真人素材组","（",[200,986,423],{},"），该组背后是真实的真人上游组，客户端无需知晓上游组 id。",[258,989,990,999],{},[261,991,992],{},[264,993,994,997],{},[267,995,996],{},"行为",[267,998,503],{},[274,1000,1001,1009,1020],{},[264,1002,1003,1006],{},[279,1004,1005],{},"一次性",[279,1007,1008],{},"成功后会话被销毁，不能重复使用",[264,1010,1011,1014],{},[279,1012,1013],{},"失败",[279,1015,1016,1017],{},"会话不存在、过期或回调未到达，均返回 ",[200,1018,1019],{},"401 InvalidVisualValidate",[264,1021,1022,1025],{},[279,1023,1024],{},"有效期",[279,1026,1027],{},"30 分钟（自回调收到时起算）",[229,1029,1031],{"id":1030},"上传真人素材-createasset","④ 上传真人素材 CreateAsset",[205,1033,1036],{"className":1034,"code":1035,"language":210},[208],"POST \u002Fapi\u002Fark?Action=CreateAsset&Version=2024-01-01\n",[200,1037,1035],{"__ignoreMap":213},[191,1039,488],{},[258,1041,1042,1052],{},[261,1043,1044],{},[264,1045,1046,1048,1050],{},[267,1047,497],{},[267,1049,500],{},[267,1051,503],{},[274,1053,1054,1065,1077,1098],{},[264,1055,1056,1060,1062],{},[279,1057,1058],{},[200,1059,423],{},[279,1061,514],{},[279,1063,1064],{},"③ 返回的 LivenessFace 组 id",[264,1066,1067,1072,1074],{},[279,1068,1069],{},[200,1070,1071],{},"URL",[279,1073,514],{},[279,1075,1076],{},"真人正脸素材的公网可访问 URL",[264,1078,1079,1084,1086],{},[279,1080,1081],{},[200,1082,1083],{},"AssetType",[279,1085,514],{},[279,1087,1088,1091,1092,1091,1095],{},[200,1089,1090],{},"Image"," \u002F ",[200,1093,1094],{},"Video",[200,1096,1097],{},"Audio",[264,1099,1100,1105,1107],{},[279,1101,1102],{},[200,1103,1104],{},"Name",[279,1106,533],{},[279,1108,1109],{},"素材名称；省略时由 URL 推导",[205,1111,1113],{"className":542,"code":1112,"language":544,"meta":213,"style":213},"{\n  \"GroupId\": \"group-01JXXXXXXXXXXXXXX\",\n  \"URL\": \"https:\u002F\u002Fyour-host.example\u002Fface.jpg\",\n  \"AssetType\": \"Image\",\n  \"Name\": \"my-face\"\n}\n",[200,1114,1115,1119,1130,1142,1154,1164],{"__ignoreMap":213},[548,1116,1117],{"class":550,"line":551},[548,1118,555],{"class":554},[548,1120,1121,1124,1126,1128],{"class":550,"line":558},[548,1122,1123],{"class":561},"  \"GroupId\"",[548,1125,565],{"class":554},[548,1127,970],{"class":568},[548,1129,572],{"class":554},[548,1131,1132,1135,1137,1140],{"class":550,"line":575},[548,1133,1134],{"class":561},"  \"URL\"",[548,1136,565],{"class":554},[548,1138,1139],{"class":568},"\"https:\u002F\u002Fyour-host.example\u002Fface.jpg\"",[548,1141,572],{"class":554},[548,1143,1144,1147,1149,1152],{"class":550,"line":586},[548,1145,1146],{"class":561},"  \"AssetType\"",[548,1148,565],{"class":554},[548,1150,1151],{"class":568},"\"Image\"",[548,1153,572],{"class":554},[548,1155,1156,1159,1161],{"class":550,"line":657},[548,1157,1158],{"class":561},"  \"Name\"",[548,1160,565],{"class":554},[548,1162,1163],{"class":568},"\"my-face\"\n",[548,1165,1166],{"class":550,"line":670},[548,1167,589],{"class":554},[191,1169,613],{},[205,1171,1173],{"className":542,"code":1172,"language":544,"meta":213,"style":213},"{\n  \"ResponseMetadata\": { \"Action\": \"CreateAsset\", \"Version\": \"2024-01-01\", \"Service\": \"ark\", \"Region\": \"cn-beijing\" },\n  \"Result\": { \"Id\": \"\u003C真实上游素材 id>\" }\n}\n",[200,1174,1175,1179,1218,1234],{"__ignoreMap":213},[548,1176,1177],{"class":550,"line":551},[548,1178,555],{"class":554},[548,1180,1181,1183,1185,1187,1189,1192,1194,1196,1198,1200,1202,1204,1206,1208,1210,1212,1214,1216],{"class":550,"line":558},[548,1182,627],{"class":561},[548,1184,916],{"class":554},[548,1186,919],{"class":561},[548,1188,565],{"class":554},[548,1190,1191],{"class":568},"\"CreateAsset\"",[548,1193,927],{"class":554},[548,1195,930],{"class":561},[548,1197,565],{"class":554},[548,1199,665],{"class":568},[548,1201,927],{"class":554},[548,1203,939],{"class":561},[548,1205,565],{"class":554},[548,1207,678],{"class":568},[548,1209,927],{"class":554},[548,1211,948],{"class":561},[548,1213,565],{"class":554},[548,1215,953],{"class":568},[548,1217,956],{"class":554},[548,1219,1220,1222,1224,1227,1229,1232],{"class":550,"line":575},[548,1221,703],{"class":561},[548,1223,916],{"class":554},[548,1225,1226],{"class":561},"\"Id\"",[548,1228,565],{"class":554},[548,1230,1231],{"class":568},"\"\u003C真实上游素材 id>\"",[548,1233,973],{"class":554},[548,1235,1236],{"class":550,"line":586},[548,1237,589],{"class":554},[215,1239,1240],{},[191,1241,1242,1243,1246,1247,1250,1251,1254],{},"平台按",[195,1244,1245],{},"目标组的类型","自动路由上游组：指向 LivenessFace 组即上传到真人上游组，无需（也不必）在请求里传 ",[200,1248,1249],{},"GroupType","。指向普通 AIGC 组则按组织级 AIGC 组入库，二者不会混淆。\n需要组织具备 AVGV2 能力，否则返回 ",[200,1252,1253],{},"403 SubscriptionRequired","。",[229,1256,1258],{"id":1257},"管理真人素材","⑤ 管理真人素材",[1260,1261,1263],"h3",{"id":1262},"查询状态-getasset","查询状态 GetAsset",[205,1265,1268],{"className":1266,"code":1267,"language":210},[208],"POST \u002Fapi\u002Fark?Action=GetAsset&Version=2024-01-01\n",[200,1269,1267],{"__ignoreMap":213},[191,1271,488,1272],{},[200,1273,1274],{},"{ \"Id\": \"\u003C素材 id>\", \"ProjectName\": \"default\" }",[191,1276,1277,1278,1281,1282,1091,1285,1091,1287,1290,1291,1293,1294,1296],{},"响应 ",[200,1279,1280],{},"Result.Status","：",[200,1283,1284],{},"Processing",[200,1286,455],{},[200,1288,1289],{},"Failed","。创建后通常先 ",[200,1292,1284],{},"，轮询直到 ",[200,1295,455],{}," 才可用于视频生成。",[1260,1298,1300],{"id":1299},"列出素材-listassets","列出素材 ListAssets",[205,1302,1305],{"className":1303,"code":1304,"language":210},[208],"POST \u002Fapi\u002Fark?Action=ListAssets&Version=2024-01-01\n",[200,1306,1304],{"__ignoreMap":213},[191,1308,1309,1310,984,1313,598,1316,598,1318,598,1321,1323,1324,178,1327,1330,1331,178,1334,1337,1338,1341,1342,1345,1346,1349],{},"请求体支持 ",[200,1311,1312],{},"Filter",[200,1314,1315],{},"GroupIds",[200,1317,1249],{},[200,1319,1320],{},"Statuses",[200,1322,1104],{},"）、分页（",[200,1325,1326],{},"PageNumber",[200,1328,1329],{},"PageSize","，最大 100）与排序（",[200,1332,1333],{},"SortBy",[200,1335,1336],{},"SortOrder","，如 ",[200,1339,1340],{},"SortBy=CreateTime&SortOrder=Desc","）。",[200,1343,1344],{},"Filter.GroupType"," 传 ",[200,1347,1348],{},"LivenessFace"," 可只列真人素材。",[1260,1351,1353],{"id":1352},"删除素材-deleteasset","删除素材 DeleteAsset",[205,1355,1358],{"className":1356,"code":1357,"language":210},[208],"POST \u002Fapi\u002Fark?Action=DeleteAsset&Version=2024-01-01\n",[200,1359,1357],{"__ignoreMap":213},[191,1361,488,1362,1364],{},[200,1363,1274],{},"。同步删除火山上游素材与本地记录。",[229,1366,1367],{"id":1367},"在视频生成中引用",[191,1369,1370,1371,1373,1374,472,1376,1379],{},"真人素材 ",[200,1372,455],{}," 后，在视频生成的 ",[200,1375,471],{},[200,1377,1378],{},"asset:\u002F\u002F\u003C素材 id>"," 引用：",[205,1381,1383],{"className":542,"code":1382,"language":544,"meta":213,"style":213},"{\n  \"model\": \"\u003CMODEL_CALL_NAME>\",\n  \"content\": [\n    {\"type\": \"image_url\", \"image_url\": {\"url\": \"asset:\u002F\u002F\u003C素材 id>\"}, \"role\": \"reference_image\"},\n    {\"type\": \"text\", \"text\": \"让画面中的角色跳舞\"}\n  ]\n}\n",[200,1384,1385,1389,1401,1409,1451,1473,1478],{"__ignoreMap":213},[548,1386,1387],{"class":550,"line":551},[548,1388,555],{"class":554},[548,1390,1391,1394,1396,1399],{"class":550,"line":558},[548,1392,1393],{"class":561},"  \"model\"",[548,1395,565],{"class":554},[548,1397,1398],{"class":568},"\"\u003CMODEL_CALL_NAME>\"",[548,1400,572],{"class":554},[548,1402,1403,1406],{"class":550,"line":575},[548,1404,1405],{"class":561},"  \"content\"",[548,1407,1408],{"class":554},": [\n",[548,1410,1411,1414,1417,1419,1422,1424,1426,1429,1432,1434,1437,1440,1443,1445,1448],{"class":550,"line":586},[548,1412,1413],{"class":554},"    {",[548,1415,1416],{"class":561},"\"type\"",[548,1418,565],{"class":554},[548,1420,1421],{"class":568},"\"image_url\"",[548,1423,927],{"class":554},[548,1425,1421],{"class":561},[548,1427,1428],{"class":554},": {",[548,1430,1431],{"class":561},"\"url\"",[548,1433,565],{"class":554},[548,1435,1436],{"class":568},"\"asset:\u002F\u002F\u003C素材 id>\"",[548,1438,1439],{"class":554},"}, ",[548,1441,1442],{"class":561},"\"role\"",[548,1444,565],{"class":554},[548,1446,1447],{"class":568},"\"reference_image\"",[548,1449,1450],{"class":554},"},\n",[548,1452,1453,1455,1457,1459,1462,1464,1466,1468,1471],{"class":550,"line":657},[548,1454,1413],{"class":554},[548,1456,1416],{"class":561},[548,1458,565],{"class":554},[548,1460,1461],{"class":568},"\"text\"",[548,1463,927],{"class":554},[548,1465,1461],{"class":561},[548,1467,565],{"class":554},[548,1469,1470],{"class":568},"\"让画面中的角色跳舞\"",[548,1472,589],{"class":554},[548,1474,1475],{"class":550,"line":670},[548,1476,1477],{"class":554},"  ]\n",[548,1479,1480],{"class":550,"line":683},[548,1481,589],{"class":554},[215,1483,1484],{},[191,1485,1486,1487,1490,1491,1494,1495,1254],{},"视频生成走自有接口 + API Key（",[200,1488,1489],{},"sk_live_","），不是 AK\u002FSK 签名；",[200,1492,1493],{},"model"," 使用模型广场的真实调用名。详见",[221,1496,1498],{"href":1497},"\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Foverview","视频生成 API",[229,1500,1501],{"id":1501},"错误码",[258,1503,1504,1514],{},[261,1505,1506],{},[264,1507,1508,1511],{},[267,1509,1510],{},"Code",[267,1512,1513],{},"含义",[274,1515,1516,1526,1539,1558,1574,1584,1597],{},[264,1517,1518,1523],{},[279,1519,1520],{},[200,1521,1522],{},"InvalidSignature",[279,1524,1525],{},"签名校验失败（AK\u002FSK 错、请求被篡改、时钟偏移过大）",[264,1527,1528,1533],{},[279,1529,1530],{},[200,1531,1532],{},"InvalidVisualValidate",[279,1534,1535,1536,1538],{},"认证会话无效、过期或认证未完成（",[200,1537,417],{}," 所有失败路径，HTTP 401）",[264,1540,1541,1549],{},[279,1542,1543,1091,1546],{},[200,1544,1545],{},"MissingParameter.*",[200,1547,1548],{},"InvalidParameter.*",[279,1550,1551,1552,1554,1555,1557],{},"缺少必填字段 \u002F 字段值非法（如 ",[200,1553,397],{}," 非 http(s)、",[200,1556,1083],{}," 非法）",[264,1559,1560,1571],{},[279,1561,1562,1091,1565,1091,1568],{},[200,1563,1564],{},"NotFound.project",[200,1566,1567],{},"NotFound.group_id",[200,1569,1570],{},"NotFound.asset_id",[279,1572,1573],{},"项目 \u002F 素材组 \u002F 素材不存在",[264,1575,1576,1581],{},[279,1577,1578],{},[200,1579,1580],{},"SubscriptionRequired",[279,1582,1583],{},"组织未开通相应能力（如 AVGV2）",[264,1585,1586,1591],{},[279,1587,1588],{},[200,1589,1590],{},"UpstreamError.Asset",[279,1592,1593,1594],{},"上游素材服务错误，透传上游原因，响应头带 ",[200,1595,1596],{},"X-Upstream-Request-Id",[264,1598,1599,1604],{},[279,1600,1601],{},[200,1602,1603],{},"InternalError",[279,1605,1606,1607,1610],{},"服务内部错误，记录 ",[200,1608,1609],{},"RequestId"," 联系支持",[229,1612,1613],{"id":1613},"注意事项",[1615,1616,1617,1625,1635,1643,1649],"ul",{},[236,1618,1619,1281,1622,1624],{},[195,1620,1621],{},"H5 一次性 + 30 分钟有效期",[200,1623,375],{}," 只能使用一次，会话 30 分钟内有效；超时需重新创建会话。",[236,1626,1627,1630,1631,1634],{},[195,1628,1629],{},"回调地址必须公网可达","：火山引擎通过浏览器跳转回调，",[200,1632,1633],{},"localhost","\u002F内网地址不可用。",[236,1636,1637,1640,1641,1634],{},[195,1638,1639],{},"素材 URL 必须公网可访问","：平台拉取素材入库，",[200,1642,1633],{},[236,1644,1645,1648],{},[195,1646,1647],{},"素材为本人正脸","：请遵守相关法律法规与平台服务条款，勿上传他人肖像素材。",[236,1650,1651,1654,1655,1657],{},[195,1652,1653],{},"素材按项目隔离","：上传与查询需使用同一 ",[200,1656,248],{},"；视频生成需使用素材所在项目。",[229,1659,1660],{"id":1660},"参考",[1615,1662,1663,1671],{},[236,1664,1665,1666,1668,1669],{},"本平台的",[221,1667,609],{"href":608},"与",[221,1670,1498],{"href":1497},[236,1672,1673,1674,598,1677],{},"火山引擎官方文档：",[221,1675,226],{"href":223,"rel":1676},[225],[221,1678,1681],{"href":1679,"rel":1680},"https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F82379\u002F2333589?lang=zh",[225],"私域真人人像素材资产使用指南",[1683,1684,1685],"style",{},"html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":213,"searchDepth":558,"depth":558,"links":1687},[1688,1689,1690,1691,1692,1693,1694,1699,1700,1701,1702],{"id":231,"depth":558,"text":231},{"id":337,"depth":558,"text":337},{"id":478,"depth":558,"text":479},{"id":786,"depth":558,"text":787},{"id":842,"depth":558,"text":843},{"id":1030,"depth":558,"text":1031},{"id":1257,"depth":558,"text":1258,"children":1695},[1696,1697,1698],{"id":1262,"depth":575,"text":1263},{"id":1299,"depth":575,"text":1300},{"id":1352,"depth":575,"text":1353},{"id":1367,"depth":558,"text":1367},{"id":1501,"depth":558,"text":1501},{"id":1613,"depth":558,"text":1613},{"id":1660,"depth":558,"text":1660},"通过人脸活体认证建立私域真人人像库，并用真人素材生成视频。","md",{},"\u002Fmodels\u002Fvideo\u002Fliveness-verification","---\ntitle: 人像认证（真人活体认证）\ndescription: 通过人脸活体认证建立私域真人人像库，并用真人素材生成视频。\nnavigation: false\n---\n\n# 人像认证（真人活体认证）\n\nSilvaMux 提供与火山引擎一致的「真人认证」人脸活体识别接口。客户可以拉起火山 H5 活体认证页面，完成本人认证后把正脸素材入库为**真人素材（LivenessFace）**，再通过 `asset:\u002F\u002F\u003CId>` 在视频生成中引用，构成私域真人人像库的完整闭环：\n\n```\n拉起活体认证 H5 → 用户完成认证 → 回调 → 获取真人素材组 → 上传真人素材 → 生成视频\n```\n\n> 接口行为与火山引擎「管理私域素材库」一致（[拉起真人认证 H5（CreateVisualValidateSession）](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F82379\u002F2333587?lang=zh)），只是 Endpoint 指向本平台、鉴权凭证使用平台签发的 AK\u002FSK。\n\n## 接入准备\n\n1. 控制台 → 凭据管理 → 创建 **Volcengine 兼容 (AK\u002FSK)** 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。\n2. AK\u002FSK 绑定组织，项目通过 `ProjectName` 字段指定（留空或填 `default` 使用默认项目）。\n3. 使用火山引擎官方 SDK 或自定义 V4 签名，请求发送到本平台：\n\n| 项 | 值 |\n| --- | --- |\n| Endpoint | `https:\u002F\u002Fwww.silvamux.com\u002Fapi\u002Fark` |\n| Region | `cn-beijing` |\n| Service | `ark` |\n| Version | `2024-01-01` |\n| 鉴权 | 火山 V4 签名，使用平台签发的 AK\u002FSK |\n| 调用方式 | `POST \u002Fapi\u002Fark?Action=\u003CAction>&Version=2024-01-01` |\n\n## 整体流程\n\n| 步骤 | 动作 | 接口 | 结果 |\n| --- | --- | --- | --- |\n| ① | 发起真人认证 | `CreateVisualValidateSession` | `H5Link` + `BytedToken`（会话 id） |\n| ② | 用户打开 H5 完成活体认证 | 浏览器跳转，平台回调 | 自动跳回你的 `CallbackURL`，带 `bytedToken` + `resultCode` |\n| ③ | 确认认证结果并获取素材组 | `GetVisualValidateResult` | 生成并返回 `GroupId`（LivenessFace 真人素材组，一次性） |\n| ④ | 上传真人素材 | `CreateAsset`（指向 ③ 的 `GroupId`） | 返回真实上游素材 `Id`，轮询 `GetAsset` 至 `Active` |\n| ⑤ | 生成视频 | 视频生成接口 | `content` 中用 `asset:\u002F\u002F\u003CId>` 引用 |\n\n## ① 创建认证会话 CreateVisualValidateSession\n\n```\nPOST \u002Fapi\u002Fark?Action=CreateVisualValidateSession&Version=2024-01-01\n```\n\n请求体：\n\n| 字段 | 必填 | 说明 |\n| --- | --- | --- |\n| `CallbackURL` | 是 | 认证完成后接收结果的回调地址，必须是 `http`\u002F`https` URL |\n| `ProjectName` | 否 | 项目名；留空或 `default` 使用默认项目 |\n\n```json\n{\n  \"CallbackURL\": \"https:\u002F\u002Fyour-host.example\u002Fcallback\",\n  \"ProjectName\": \"default\"\n}\n```\n\n> 请求使用平台签发的 AK\u002FSK 做火山 V4 签名（`Service=ark`、`Region=cn-beijing`、`Version=2024-01-01`），具体签名方式见[素材管理](\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Fassets)接入说明。\n\n响应：\n\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"3f2f8b4d1a6e4c5b9a7d0e2f1c3b4a5d\",\n    \"Action\": \"CreateVisualValidateSession\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"H5Link\": \"https:\u002F\u002F...（火山 H5 活体认证页面）\",\n    \"BytedToken\": \"VVS-01JXXXXXXXXXXXXXX\"\n  }\n}\n```\n\n| 字段 | 说明 |\n| --- | --- |\n| `H5Link` | 让用户在浏览器（手机\u002FPC）打开的活体认证页面 |\n| `BytedToken` | **平台会话 id**，后续 `GetVisualValidateResult` 使用它作为 `BytedToken` |\n\n> H5 链接仅能使用一次，会话有效期 30 分钟。\n\n## ② 认证回调\n\n用户打开 `H5Link` 完成眨眼\u002F转头等活体动作后，火山引擎把用户浏览器重定向到平台回调；平台记录认证结果后，用一个 HTML 页面把浏览器自动跳转到你提供的 `CallbackURL`，并附加参数：\n\n| 参数 | 说明 |\n| --- | --- |\n| `bytedToken` | 平台会话 id（与 ① 返回的 `BytedToken` 相同） |\n| `resultCode` | `10000` 表示认证通过 |\n\n你的回调服务可据此展示「认证结果」，随后调用 `GetVisualValidateResult` 正式获取素材组。\n\n## ③ 获取真人素材组 GetVisualValidateResult\n\n```\nPOST \u002Fapi\u002Fark?Action=GetVisualValidateResult&Version=2024-01-01\n```\n\n请求体：\n\n| 字段 | 必填 | 说明 |\n| --- | --- | --- |\n| `BytedToken` | 是 | ① 返回的会话 id |\n\n```json\n{\n  \"BytedToken\": \"VVS-01JXXXXXXXXXXXXXX\"\n}\n```\n\n响应：\n\n```json\n{\n  \"ResponseMetadata\": { \"Action\": \"GetVisualValidateResult\", \"Version\": \"2024-01-01\", \"Service\": \"ark\", \"Region\": \"cn-beijing\" },\n  \"Result\": { \"GroupId\": \"group-01JXXXXXXXXXXXXXX\" }\n}\n```\n\n成功后平台会创建并返回一个 **LivenessFace 真人素材组**（`GroupId`），该组背后是真实的真人上游组，客户端无需知晓上游组 id。\n\n| 行为 | 说明 |\n| --- | --- |\n| 一次性 | 成功后会话被销毁，不能重复使用 |\n| 失败 | 会话不存在、过期或回调未到达，均返回 `401 InvalidVisualValidate` |\n| 有效期 | 30 分钟（自回调收到时起算） |\n\n## ④ 上传真人素材 CreateAsset\n\n```\nPOST \u002Fapi\u002Fark?Action=CreateAsset&Version=2024-01-01\n```\n\n请求体：\n\n| 字段 | 必填 | 说明 |\n| --- | --- | --- |\n| `GroupId` | 是 | ③ 返回的 LivenessFace 组 id |\n| `URL` | 是 | 真人正脸素材的公网可访问 URL |\n| `AssetType` | 是 | `Image` \u002F `Video` \u002F `Audio` |\n| `Name` | 否 | 素材名称；省略时由 URL 推导 |\n\n```json\n{\n  \"GroupId\": \"group-01JXXXXXXXXXXXXXX\",\n  \"URL\": \"https:\u002F\u002Fyour-host.example\u002Fface.jpg\",\n  \"AssetType\": \"Image\",\n  \"Name\": \"my-face\"\n}\n```\n\n响应：\n\n```json\n{\n  \"ResponseMetadata\": { \"Action\": \"CreateAsset\", \"Version\": \"2024-01-01\", \"Service\": \"ark\", \"Region\": \"cn-beijing\" },\n  \"Result\": { \"Id\": \"\u003C真实上游素材 id>\" }\n}\n```\n\n> 平台按**目标组的类型**自动路由上游组：指向 LivenessFace 组即上传到真人上游组，无需（也不必）在请求里传 `GroupType`。指向普通 AIGC 组则按组织级 AIGC 组入库，二者不会混淆。\n> 需要组织具备 AVGV2 能力，否则返回 `403 SubscriptionRequired`。\n\n## ⑤ 管理真人素材\n\n### 查询状态 GetAsset\n\n```\nPOST \u002Fapi\u002Fark?Action=GetAsset&Version=2024-01-01\n```\n\n请求体：`{ \"Id\": \"\u003C素材 id>\", \"ProjectName\": \"default\" }`\n\n响应 `Result.Status`：`Processing` \u002F `Active` \u002F `Failed`。创建后通常先 `Processing`，轮询直到 `Active` 才可用于视频生成。\n\n### 列出素材 ListAssets\n\n```\nPOST \u002Fapi\u002Fark?Action=ListAssets&Version=2024-01-01\n```\n\n请求体支持 `Filter`（`GroupIds`、`GroupType`、`Statuses`、`Name`）、分页（`PageNumber`\u002F`PageSize`，最大 100）与排序（`SortBy`\u002F`SortOrder`，如 `SortBy=CreateTime&SortOrder=Desc`）。`Filter.GroupType` 传 `LivenessFace` 可只列真人素材。\n\n### 删除素材 DeleteAsset\n\n```\nPOST \u002Fapi\u002Fark?Action=DeleteAsset&Version=2024-01-01\n```\n\n请求体：`{ \"Id\": \"\u003C素材 id>\", \"ProjectName\": \"default\" }`。同步删除火山上游素材与本地记录。\n\n## 在视频生成中引用\n\n真人素材 `Active` 后，在视频生成的 `content` 中用 `asset:\u002F\u002F\u003C素材 id>` 引用：\n\n```json\n{\n  \"model\": \"\u003CMODEL_CALL_NAME>\",\n  \"content\": [\n    {\"type\": \"image_url\", \"image_url\": {\"url\": \"asset:\u002F\u002F\u003C素材 id>\"}, \"role\": \"reference_image\"},\n    {\"type\": \"text\", \"text\": \"让画面中的角色跳舞\"}\n  ]\n}\n```\n\n> 视频生成走自有接口 + API Key（`sk_live_`），不是 AK\u002FSK 签名；`model` 使用模型广场的真实调用名。详见[视频生成 API](\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Foverview)。\n\n## 错误码\n\n| Code | 含义 |\n| --- | --- |\n| `InvalidSignature` | 签名校验失败（AK\u002FSK 错、请求被篡改、时钟偏移过大） |\n| `InvalidVisualValidate` | 认证会话无效、过期或认证未完成（`GetVisualValidateResult` 所有失败路径，HTTP 401） |\n| `MissingParameter.*` \u002F `InvalidParameter.*` | 缺少必填字段 \u002F 字段值非法（如 `CallbackURL` 非 http(s)、`AssetType` 非法） |\n| `NotFound.project` \u002F `NotFound.group_id` \u002F `NotFound.asset_id` | 项目 \u002F 素材组 \u002F 素材不存在 |\n| `SubscriptionRequired` | 组织未开通相应能力（如 AVGV2） |\n| `UpstreamError.Asset` | 上游素材服务错误，透传上游原因，响应头带 `X-Upstream-Request-Id` |\n| `InternalError` | 服务内部错误，记录 `RequestId` 联系支持 |\n\n## 注意事项\n\n- **H5 一次性 + 30 分钟有效期**：`H5Link` 只能使用一次，会话 30 分钟内有效；超时需重新创建会话。\n- **回调地址必须公网可达**：火山引擎通过浏览器跳转回调，`localhost`\u002F内网地址不可用。\n- **素材 URL 必须公网可访问**：平台拉取素材入库，`localhost`\u002F内网地址不可用。\n- **素材为本人正脸**：请遵守相关法律法规与平台服务条款，勿上传他人肖像素材。\n- **素材按项目隔离**：上传与查询需使用同一 `ProjectName`；视频生成需使用素材所在项目。\n\n## 参考\n\n- 本平台的[素材管理](\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Fassets)与[视频生成 API](\u002Fzh-cn\u002Fdocs\u002Fmodels\u002Fvideo\u002Foverview)\n- 火山引擎官方文档：[拉起真人认证 H5（CreateVisualValidateSession）](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F82379\u002F2333587?lang=zh)、[私域真人人像素材资产使用指南](https:\u002F\u002Fdocs.volcengine.com\u002Fdocs\u002F82379\u002F2333589?lang=zh)\n",[],{"title":182,"description":1703},"4.models\u002F3.video\u002F4.liveness-verification","9UZtqq0Q0D5axIrHWhuz1FZYyZZUAhEbW8B2A93mIp8"]