RealFace Enrollment
Enroll a real person's face as a ta_xxxxxxxx asset you can pass as real_face_asset_id on any Seedance 2.0 / 2.0 Fast / 2.0 Mini call. Use this when you want a real person to appear consistently across multiple videos (talking head, spokesperson, character continuity).
No government ID, no account login, no name verification. Just a brief on-phone liveness check (nod + blink, ~1 minute) that proves the person enrolling is the same as the person in the photo. The biometric data is processed by the upstream identity service — BlockRun never sees it. For purely AI-generated characters (no real person involved), use Virtual Portrait instead ($0.011, no liveness step).
| Endpoints | POST /v1/realface/init (free, returns h5Link) · POST /v1/realface/enroll ($0.011 USDC, finalizes) · GET /v1/realface/status?groupId=… (free polling) |
| Price | $0.011 USDC per enrollment, one-time, settled to BlockRun's Base wallet via x402 |
| Auth | x402 micropayment header on finalize — no API key needed |
| Network | Base (USDC, EIP-3009 exact) |
| Returns | ta_xxxxxxxx… asset id, usable as real_face_asset_id on Seedance 2.0 / 2.0 Fast / 2.0 Mini |
You can use the web UI at blockrun.ai/studio/realface — connect wallet, paste image URL, get QR for the rights-holder to scan, pay $0.011, copy the ta_xxx. The endpoints below are for SDK / programmatic use.
Flow
[1] POST /v1/realface/init — FREE, rate-limited
body: { "name": "..." }
→ { group_id: "rf1_…",
h5_link: "https://kyc.byteintl.com/?...",
expires_in_seconds: 120 }
[2] The rights-holder scans h5_link on their phone (use it as a QR code or
just open it on mobile). They complete a brief liveness check —
record a 2-4 second video doing two prompted actions (nod, blink).
NO login, NO ID upload, NO personal info.
[3] GET /v1/realface/status?groupId=rf1_… — poll every 3-5s
→ { status: "pending_validation", ready_to_finalize: false }
→ ... (after H5 completes)
→ { status: "active", ready_to_finalize: true }
[4] POST /v1/realface/enroll — PAID ($0.011 USDC)
body: { "name": "...", "image_url": "https://...", "group_id": "..." }
headers: { "x-payment": "<x402 base64>" }
→ { asset_id: "ta_…", group_id: "...", ... }
The whole sequence typically completes in under 3 minutes (mostly the user finding their phone and tapping through the H5).
Using the enrolled ta_xxx
Pass it as real_face_asset_id on any Seedance 2.0 / 2.0 Fast / 2.0 Mini call:
curl -X POST http://localhost:8402/v1/videos/generations \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedance-2.0-fast",
"prompt": "she smiles warmly and waves at the camera in soft studio light",
"real_face_asset_id": "ta_f85b20b9394e47be9502d819bee7929c"
}'
The same ta_xxx can be reused across as many videos as you want — pay only the per-clip token cost each time. No re-enrollment fee. The video call must be paid by the same wallet that enrolled the asset: an asset id is not a secret (the listing below is public), so a call paid by any other wallet is refused with 403 before anything is charged.
Listing enrolled RealFaces
GET https://blockrun.ai/api/v1/wallet/<address>/realfaces
Returns the wallet's enrolled RealFaces. Free, rate-limited (same 120/hour/IP bucket as /portraits); accepts EVM 0x… or Solana base58 addresses (400 otherwise). Responses are cacheable for 30 s.
{
"wallet": "0xYourWalletAddress",
"realfaces": [
{
"assetId": "ta_f85b20b9394e47be9502d819bee7929c",
"name": "Spokesperson — Q3 campaign",
"imageUrl": "https://example.com/person.jpg",
"createdAt": "2026-05-24T16:19:00.000Z",
"enrollmentTxHash": "0x…",
"byteplusAssetId": "asset-20260525001905-…"
}
],
"count": 1
}
The video playground reads this same list and shows it in the real_face_asset_id dropdown alongside your Virtual Portraits.
Error codes
| Code | When | Did payment settle? |
|---|---|---|
| 400 | Invalid request body, bad image URL; on /status, a missing groupId | – (pre-payment) |
| 402 | Payment Required (first probe), or payment verification failed with code PAYMENT_INVALID / PAYMENT_UNFUNDED / PAYMENT_BLOCKHASH_STALE / PAYMENT_REPLAY | – |
| 404 | group_id is not a handle this service issued, or the group no longer exists — one answer for both, so group existence stays unreadable | – |
| 425 | group_id is in pending_validation — the rights-holder hasn't completed the H5 yet | No |
| 422 | Image rejected by the face service, or face-match failed — uploaded photo doesn't match the live H5 face | No |
| 429 | Rate limit on /init (10/hour/IP), /status or the listing (120/hour/IP) | – |
| 502 | Upstream failure on /init, /status, the group-status check or the upload | No |
| 200 | Asset enrolled and active | Yes |
Storage and privacy
- Wallet → enrolled RealFace list is stored by BlockRun
- Request content you send to blockrun.ai (Base) — the request body, including the name and image URL, and the response — is retained by BlockRun. The Solana gateway (sol.blockrun.ai) stores no request content
- The image URL you supplied is kept for previewing in the UI
- The face/liveness data goes directly from the rights-holder's phone to the upstream identity service — BlockRun servers never receive face image bytes during the H5
- We do not analyze, redistribute, or use enrolled faces for any purpose other than serving the asset id back to your wallet and forwarding requests for Seedance generation
Comparison with Virtual Portrait
| Virtual Portrait | RealFace | |
|---|---|---|
| Asset target | AI-generated character | Real person |
| Price | $0.011 USDC | $0.011 USDC |
| Liveness check | Not required | Required (~1 minute on phone) |
| Upstream verification | None | Biometric match against H5 live face |
| Government ID | Not required | Not required |
| Compatible models | Seedance 2.0 / 2.0 Fast / 2.0 Mini | Seedance 2.0 / 2.0 Fast / 2.0 Mini |
What's next?
Pass the ta_xxx you just enrolled as real_face_asset_id on a Seedance 2.0 / 2.0 Fast / 2.0 Mini call.
The zero-liveness option for AI-generated characters — same ta_xxx mechanic, $0.011.
How the 402 / sign / retry handshake works behind the paid finalize call.
Also useful: Real-person video walkthrough (screenshots) · RealFace Studio UI (web flow for non-developers).