RealFace 与虚拟肖像 API

注册真人（含活体验证）或合成角色，实现 AI 生成视频中一致的身份特征。创建可复用的 ta_xxx asset_id，用于 Seedance 2.0 视频生成。

基础 URL： https://api.jarvisclaw.ai/v1/marketplace/realface

认证

两种方式均支持：

方式	Header	描述
API Key	`Authorization: Bearer sk-...`	平台自动从你的 HD 钱包签名 x402
私钥 (x402)	SDK 自动处理	Agent 直接用自己的钱包签名 x402

定价

下表为参考价。精确扣费金额请读响应中的 price.amount。

方法	端点	价格	描述
POST	`/realface/init`	$0.005	初始化活体验证会话
GET	`/realface/status`	$0.001	轮询会话状态
POST	`/realface/enroll`	$0.01	完成注册（活体通过后）
POST	`/realface/portrait/enroll`	$0.01	注册虚拟肖像（无活体验证）
GET	`/realface/assets`	$0.001	列出已注册资产
GET	`/realface/assets/:id`	$0.001	获取资产详情

/init 与只读接口都不是免费的

早前文档把 /init 和只读接口标为 $0，实际是计费的。 GET 类只读接口按 $0.001 计费，并非免费。

端点

方法	端点	描述
POST	/init	初始化活体验证会话
POST	/enroll	注册真人面部（需完成活体验证）
POST	/portrait/enroll	注册虚拟肖像（跳过活体）
GET	/assets	列出所有已注册资产
GET	/asset/:id	获取指定资产详情
POST	/group/create	创建资产分组
POST	/group/:id/add	向分组添加资产

POST /init

初始化活体验证会话。返回一个会话 URL，真人需在该页面完成活体挑战（眨眼、转头等）。

参数

参数	类型	必填	描述
`name`	string	是	注册者姓名（用于标识）
`callback_url`	string	否	活体完成后的回调 URL

响应

json

{
  "session_id": "sess_abc123",
  "liveness_url": "https://verify.jarvisclaw.ai/liveness/sess_abc123",
  "expires_at": "2026-07-06T11:00:00Z",
  "status": "pending"
}

POST /enroll

活体验证通过后，提交参考照片完成注册。返回可复用的 asset_id。

参数

参数	类型	必填	描述
`session_id`	string	是	已完成活体验证的会话 ID
`reference_image_url`	string	是	清晰正面照片 URL（单人）
`group_id`	string	否	关联到已有分组

响应

json

{
  "asset_id": "ta_real_7f8a9b2c",
  "name": "John Doe",
  "type": "realface",
  "status": "active",
  "created_at": "2026-07-06T10:35:00Z",
  "liveness_verified": true
}

POST /portrait/enroll

注册虚拟肖像（AI 角色、插画、3D 渲染等）。无需活体验证。

参数

参数	类型	必填	描述
`name`	string	是	角色名称
`image_url`	string	是	角色图片 URL
`group_id`	string	否	关联到已有分组

响应

json

{
  "asset_id": "ta_port_3e4f5a6b",
  "name": "Cyber Knight",
  "type": "portrait",
  "status": "active",
  "created_at": "2026-07-06T10:36:00Z",
  "liveness_verified": false
}

GET /assets

列出所有已注册资产（真人 + 虚拟肖像）。

参数

参数	类型	必填	描述
`type`	string	否	过滤类型：`realface`、`portrait`
`group_id`	string	否	按分组过滤

响应

json

{
  "assets": [
    {
      "asset_id": "ta_real_7f8a9b2c",
      "name": "John Doe",
      "type": "realface",
      "status": "active",
      "created_at": "2026-07-06T10:35:00Z"
    },
    {
      "asset_id": "ta_port_3e4f5a6b",
      "name": "Cyber Knight",
      "type": "portrait",
      "status": "active",
      "created_at": "2026-07-06T10:36:00Z"
    }
  ],
  "total": 2
}

POST /group/create

创建资产分组，用于组织管理多个资产。

参数

参数	类型	必填	描述
`name`	string	是	分组名称
`description`	string	否	分组描述

响应

json

{
  "group_id": "grp_abc123",
  "name": "Marketing Team",
  "created_at": "2026-07-06T10:37:00Z"
}

代码示例

bash

# 1. 初始化活体验证
curl -X POST https://api.jarvisclaw.ai/v1/marketplace/realface/init \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe"}'

# 2. 完成注册（活体通过后）
curl -X POST https://api.jarvisclaw.ai/v1/marketplace/realface/enroll \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_abc123",
    "reference_image_url": "https://example.com/john-photo.jpg"
  }'

# 3. 注册虚拟肖像（无需活体）
curl -X POST https://api.jarvisclaw.ai/v1/marketplace/realface/portrait/enroll \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cyber Knight",
    "image_url": "https://example.com/character.png"
  }'

# 4. 列出所有资产
curl https://api.jarvisclaw.ai/v1/marketplace/realface/assets \
  -H "Authorization: Bearer sk-your-api-key"

python

import requests

BASE = "https://api.jarvisclaw.ai/v1/marketplace/realface"
HEADERS = {
    "Authorization": "Bearer sk-your-api-key",
    "Content-Type": "application/json",
}

# 1. 初始化活体验证会话
resp = requests.post(f"{BASE}/init", headers=HEADERS, json={
    "name": "John Doe",
})
session = resp.json()
print(f"活体验证 URL: {session['liveness_url']}")
print(f"请在 {session['expires_at']} 前完成验证")

# 2. 用户完成活体验证后，注册面部
resp = requests.post(f"{BASE}/enroll", headers=HEADERS, json={
    "session_id": session["session_id"],
    "reference_image_url": "https://example.com/john-photo.jpg",
})
asset = resp.json()
print(f"注册成功！Asset ID: {asset['asset_id']}")

# 3. 注册虚拟肖像（无需活体）
resp = requests.post(f"{BASE}/portrait/enroll", headers=HEADERS, json={
    "name": "Cyber Knight",
    "image_url": "https://example.com/character.png",
})
portrait = resp.json()
print(f"虚拟肖像 Asset ID: {portrait['asset_id']}")

# 4. 在视频生成中使用 asset_id
# 参见视频生成 API 文档

python

from jarvisclaw import MarketplaceClient

# x402 Agent 钱包
client = MarketplaceClient(private_key="0x<evm-private-key>")

# 创建分组
group = client.call("realface", "/group/create", method="POST", json={
    "name": "品牌大使",
})
group_id = group["group_id"]

# 初始化活体验证
session = client.call("realface", "/init", method="POST", json={
    "name": "Jane Smith",
})
print(f"活体验证链接: {session['liveness_url']}")

# 验证完成后注册
asset = client.call("realface", "/enroll", method="POST", json={
    "session_id": session["session_id"],
    "reference_image_url": "https://example.com/jane.jpg",
    "group_id": group_id,
})
print(f"Asset ID: {asset['asset_id']}")

# 虚拟肖像
portrait = client.call("realface", "/portrait/enroll", method="POST", json={
    "name": "Cyber Knight",
    "image_url": "https://example.com/character.png",
})
print(f"肖像: {portrait['asset_id']}")

package main

import (
    "context"
    "fmt"
    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()
    mc, _ := jc.NewMarketplaceClient(jc.WithAPIKey("sk-your-api-key"))

    // 初始化活体验证
    session, _ := mc.Post(ctx, "realface", "/init", map[string]interface{}{
        "name": "John Doe",
    })
    fmt.Printf("验证链接: %s\n", session["liveness_url"])

    // 注册（活体通过后）
    asset, _ := mc.Post(ctx, "realface", "/enroll", map[string]interface{}{
        "session_id":          session["session_id"],
        "reference_image_url": "https://example.com/john.jpg",
    })
    fmt.Printf("Asset ID: %s\n", asset["asset_id"])

    // 虚拟肖像
    portrait, _ := mc.Post(ctx, "realface", "/portrait/enroll", map[string]interface{}{
        "name":      "Cyber Knight",
        "image_url": "https://example.com/character.png",
    })
    fmt.Printf("肖像 ID: %s\n", portrait["asset_id"])
}

package main

import (
    "context"
    "fmt"
    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()
    mc, _ := jc.NewMarketplaceClient(jc.WithPrivateKey("0x<evm-private-key>"))

    // 初始化活体验证
    session, _ := mc.Post(ctx, "realface", "/init", map[string]interface{}{
        "name": "John Doe",
    })
    fmt.Printf("验证链接: %s\n", session["liveness_url"])

    // 注册面部
    asset, _ := mc.Post(ctx, "realface", "/enroll", map[string]interface{}{
        "session_id":          session["session_id"],
        "reference_image_url": "https://example.com/john.jpg",
    })
    fmt.Printf("Asset ID: %s\n", asset["asset_id"])
}

与视频生成集成

注册完成后，在视频生成 API 中使用 real_face_asset_id 参数：

bash

curl -X POST https://api.jarvisclaw.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "这个人在镜头前微笑并挥手",
    "real_face_asset_id": "ta_real_7f8a9b2c",
    "duration_seconds": 5
  }'

注意：仅 Seedance 2.0 和 2.0 Fast 支持 real_face_asset_id，1.5 Pro 不支持。

错误

代码	名称	描述	解决方案
400	session_expired	活体会话已过期	重新调用 /init 创建新会话
400	liveness_failed	活体验证未通过	确保面部清晰可见，重新验证
400	multiple_faces	图片中检测到多张面孔	使用仅包含一张面孔的照片
400	invalid_image	图片无法处理	使用清晰的正面照片，JPEG/PNG 格式
404	asset_not_found	Asset ID 不存在	检查 asset_id 格式是否正确

限制

注册不可撤销 — 一旦注册完成，asset_id 永久有效，无法撤销
虚拟肖像跳过验证 — /portrait/enroll 不验证身份，任何人都可以注册任何图片
单人照片 — 参考照片必须只包含一张清晰可见的面孔
需本人同意 — RealFace 设计为基于同意的注册，被注册人必须本人完成活体验证

RealFace 与虚拟肖像 API ​

认证 ​

定价 ​

端点 ​

POST /init ​

参数 ​

响应 ​

POST /enroll ​

参数 ​

响应 ​

POST /portrait/enroll ​

参数 ​

响应 ​

GET /assets ​

参数 ​

响应 ​

POST /group/create ​

参数 ​

响应 ​

代码示例 ​

与视频生成集成 ​

错误 ​

限制 ​

RealFace 与虚拟肖像 API

认证

定价

端点

POST /init

参数

响应

POST /enroll

参数

响应

POST /portrait/enroll

参数

响应

GET /assets

参数

响应

POST /group/create

参数

响应

代码示例

与视频生成集成

错误

限制