RealFace Enrollment

POST https://blockrun.ai/api/v1/realface/init

Request

{
  "name": "Spokesperson — Q3 campaign"
}

Response

{
  "object": "realface.init",
  "group_id": "rf1_…",
  "h5_link": "https://kyc.byteintl.com/?accessKeyId=...&sessionToken=...&configId=...",
  "status": "pending_validation",
  "expires_in_seconds": 120,
  "next_steps": { ... }
}

Send the h5_link to the rights-holder. Easiest way: render it as a QR they scan with their phone camera. The H5 page does the liveness verification — no account, no ID, just camera or video recording.

The H5 session token expires after 120 seconds. If they don't finish in time, call /init again with { "groupId": "<existing>" } to refresh.

What the rights-holder sees on their phone

Total time: ~60 seconds including the QR scan and camera permission prompt. No login, no password, no email confirmation, no ID upload, no name entry.

Alternate path (camera blocked or not available)

If they tap Deny on camera permission, the H5 offers a fallback:

1. Page shows "Use the alternate authentication method"
2. They record a 2-4 second video using the phone's native camera app, doing the same nod + blink
3. They upload the video file
4. Same end result, ~30s slower

What data leaves their phone

• Live face video (or alternate uploaded video) → the upstream identity service
• Nothing goes to BlockRun during the phone session. We don't see the video, the camera feed, or any biometric template
• The upstream service stores enough to perform a one-time face-match against the photo you supply in step 4. Once the match is decided, your photo is the asset of record — the live video is not referenced again in subsequent Seedance generations

Failure modes on the phone

No phone? Use a laptop

The H5 link works in any modern browser with a webcam. The rights-holder can open it on a laptop and grant the webcam permission — same flow.

GET https://blockrun.ai/api/v1/realface/status?groupId=rf1_…

Response

{
  "object": "realface.status",
  "group_id": "rf1_…",
  "status": "pending_validation",
  "asset_count": 0,
  "ready_to_finalize": false
}

When status transitions to "active" (and ready_to_finalize: true), the rights-holder has completed the H5 and you can move to step 4.

Poll every 3-5 seconds. Free but rate-limited (same bucket as wallet reconciliation, 120/hour/IP).

A missing groupId is 400. Anything else that is not a handle this service issued — malformed, tampered with, or for a group that does not exist — is 404 ({ "error": "Unknown group", "message": "Pass the group_id returned by POST /api/v1/realface/init." }). The two cases are deliberately not distinguished: a different answer for a real group than for an absent one would confirm which groups exist. Only a genuine upstream failure is 502.

POST https://blockrun.ai/api/v1/realface/enroll

Request

{
  "name": "Spokesperson — Q3 campaign",
  "image_url": "https://example.com/person.jpg",
  "group_id": "rf1_…"
}

x402 payment

Same two-step pattern as other paid BlockRun endpoints:

1. First call without X-Payment → server returns 402 Payment Required with x402 challenge headers (X-Payment-Required / PAYMENT-REQUIRED base64, plus WWW-Authenticate: X402 requirements="…") and a body of { "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "11000", "payTo": "0x…", "maxTimeoutSeconds": 300 }], "error": "Payment Required", "message": "Enrolling a RealFace asset costs $0.0110 USDC. …", "price": { "amount": "0.0110", "currency": "USD" }, "paymentInfo": { "network": "base", "asset": "USDC", "x402Version": 2 } } — x402Version/accepts mirror the header's challenge for clients that only read the body
2. Sign the EIP-3009 transfer authorization for $0.011 USDC on Base ($0.01 enrolment + $0.001 transaction fee — the requirements say 11000 micro-USDC)
3. Retry the same request with X-Payment: <base64> (Payment-Signature is accepted too)

Settlement happens after the upstream face-match succeeds. Failure modes that do NOT settle:

• 402 — payment verification failed: { "error": "Payment verification failed", "code": "PAYMENT_INVALID" | "PAYMENT_UNFUNDED" | "PAYMENT_BLOCKHASH_STALE", "message"?, "debug", "payer" }, or code: "PAYMENT_REPLAY" when the authorization was already used — sign a fresh one
• 425 Too Early — group is not yet active (rights-holder hasn't done H5); body carries group_status and a hint
• 422 Unprocessable — the face service rejected the image (bad/oversized photo, no clear single face; may carry a code) or the face-match failed (uploaded photo doesn't match the live face)
• 502 Bad Gateway — the upstream group-status check or the upload itself failed

If settlement itself fails after a successful enrollment, BlockRun absorbs the cost.

Response

{
  "object": "realface",
  "asset_id": "ta_f85b20b9394e47be9502d819bee7929c",
  "group_id": "rf1_…",
  "byteplus_asset_id": "asset-20260525001905-…",
  "name": "Spokesperson — Q3 campaign",
  "image_url": "https://example.com/person.jpg",
  "created_at": "2026-05-24T16:19:00.000Z",
  "usage": {
    "compatible_models": ["bytedance/seedance-2.0", "bytedance/seedance-2.0-fast", "bytedance/seedance-2.0-mini"],
    "how_to_use": "Pass \"real_face_asset_id\": \"ta_f85b20b9394e47be9502d819bee7929c\" on a Seedance video generation request."
  },
  "price": { "amount": "0.0110", "currency": "USD" },
  "settlement": {
    "success": true,
    "tx_hash": "0x…",
    "network": "base"
  }
}

The settlement receipt is also returned in the X-Payment-Response / PAYMENT-RESPONSE headers.