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).

Liveness check only

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).

EndpointsPOST /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
Authx402 micropayment header on finalize — no API key needed
NetworkBase (USDC, EIP-3009 exact)
Returnsta_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

CodeWhenDid payment settle?
400Invalid request body, bad image URL; on /status, a missing groupId– (pre-payment)
402Payment Required (first probe), or payment verification failed with code PAYMENT_INVALID / PAYMENT_UNFUNDED / PAYMENT_BLOCKHASH_STALE / PAYMENT_REPLAY–
404group_id is not a handle this service issued, or the group no longer exists — one answer for both, so group existence stays unreadable–
425group_id is in pending_validation — the rights-holder hasn't completed the H5 yetNo
422Image rejected by the face service, or face-match failed — uploaded photo doesn't match the live H5 faceNo
429Rate limit on /init (10/hour/IP), /status or the listing (120/hour/IP)–
502Upstream failure on /init, /status, the group-status check or the uploadNo
200Asset enrolled and activeYes

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 PortraitRealFace
Asset targetAI-generated characterReal person
Price$0.011 USDC$0.011 USDC
Liveness checkNot requiredRequired (~1 minute on phone)
Upstream verificationNoneBiometric match against H5 live face
Government IDNot requiredNot required
Compatible modelsSeedance 2.0 / 2.0 Fast / 2.0 MiniSeedance 2.0 / 2.0 Fast / 2.0 Mini

What's next?

Also useful: Real-person video walkthrough (screenshots) · RealFace Studio UI (web flow for non-developers).