Real-Human Asset API

The Real-Human Asset API lets you onboard a verified real person as a private, reusable portrait asset, then drive Seedance 2.0 video generation from that asset. Ownership of portrait rights is secured at the source through one-time live-face verification; once a person is verified, you can add additional photos/styles of the same person without repeating verification.

Basics

Item	Value
Base URL	`https://api.pomex.ai`
Authentication	`Authorization: Bearer <YOUR_API_KEY>`
Content type	`application/json`
Errors	JSON body `{"error": {"message", "type"}}` with standard HTTP status codes

All endpoints require a valid API key. Requests without one return 401.

Integration Flow

 ┌────────────┐   ① create session    ┌──────────┐
 │ Your       │ ────────────────────▶ │ PomexAI  │
 │ backend    │ ◀──────────────────── │ Gateway  │
 └────────────┘   h5_link             └──────────┘
       │  ② send h5_link to the end user (mobile)
       ▼
 ┌────────────┐   live-face scan      ┌──────────┐
 │ End user   │ ────────────────────▶ │ Verify   │
 │ (phone)    │                       │ service  │
 └────────────┘                       └──────────┘
       │  ③ on success, browser is 302-redirected to your callback_url
       ▼            with ?resultCode=10000&group_id=...
 ┌────────────┐   ④ upload portrait   ┌──────────┐
 │ Your       │ ────────────────────▶ │ PomexAI  │
 │ backend    │   ⑤ poll until active │ Gateway  │
 └────────────┘   ⑥ generate video    └──────────┘

Create a verification session — receive an h5_link.
The end user opens h5_link on a phone and completes a live-face scan (no upload required).
On success, the platform redirects the user's browser to your callback_url, appending group_id.
Upload a portrait of the same person using group_id and a public image URL.
Poll the asset until its status is active.
(Optional) Generate a video referencing the asset via asset://<asset_id>.

API Reference

Create Verification Session

POST /v1/video/assets/sessions

Field	Type	Required	Description
callback_url	`string`	Yes	HTTPS URL. The user's browser is 302-redirected here after verification.
lang	`string`	No	H5 page language: `zh` (default), `en`, or `zh-Hant`.

Request

curl -X POST "https://api.pomex.ai/v1/video/assets/sessions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://yourapp.com/realhuman/callback","lang":"en"}'

Response `200`

{
  "object": "video.asset_session",
  "status": "pending",
  "h5_link": "https://kyc.byteintl.com/?...&lang=en"
}

Deliver h5_link to the end user and have them complete it promptly — the link is valid for a limited time (≈30 minutes). If it expires, simply create a new session.

Verification Callback (Your Endpoint)

After the user finishes the scan, PomexAI processes the result and 302-redirects the browser to your callback_url with these query parameters:

Parameter	Description
resultCode	`10000` indicates success. Any other value is a failure.
group_id	The asset group ID for this person. Present on success. Persist this.
verify_type	Verification type, e.g. `real_time`.
algorithmBaseRespCode	Upstream sub-code (diagnostics).
reqMeasureInfoValue	Billing flag (`0` = not billed, `1` = billed).

Example redirect

https://yourapp.com/realhuman/callback?resultCode=10000&group_id=group-20260619145855-snq4q&verify_type=real_time&algorithmBaseRespCode=0&reqMeasureInfoValue=1

Read group_id only when resultCode=10000. Each group_id corresponds to exactly one real person; reuse it for all future assets of that person.

Tip: Use real-time liveness (verify_type=real_time). A pre_record result will not produce a usable group_id.

Upload an Asset

POST /v1/video/assets

Field	Type	Required	Description
url	`string`	Yes	Public HTTPS direct image link (not a web page).
asset_type	`string`	Yes	`Image`, `Video`, or `Audio` (case-sensitive).
group_id	`string`	Yes (real-human)	The `group_id` from verification. Omit to upload to your default Virtual group.
name	`string`	No	Label for management/search (not used in generation).

The uploaded portrait must be the same person who completed verification; the system performs a face-consistency check. Images with no face, multiple faces, or a mismatched person are rejected (status: failed).

Request

curl -X POST "https://api.pomex.ai/v1/video/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourcdn.com/portrait.jpg",
    "asset_type": "Image",
    "group_id": "group-20260619145855-snq4q",
    "name": "model-rachel-frontal"
  }'

Response `200`

{
  "id": "asset-20260619150241-b8xd4",
  "object": "video.asset",
  "status": "processing"
}

Upload is asynchronous; no processing-time SLA is guaranteed.

Get an Asset

GET /v1/video/assets/{asset_id}

Poll this endpoint until status becomes active (usable) or failed.

Response `200`

{
  "id": "asset-20260619150241-b8xd4",
  "object": "video.asset",
  "name": "model-rachel-frontal",
  "url": "https://.../portrait.jpg?...",
  "asset_type": "Image",
  "group_id": "group-20260619145855-snq4q",
  "status": "active",
  "created_at": "2026-06-19T07:02:41Z",
  "updated_at": "2026-06-19T07:02:46Z"
}

The signed url is valid for ≈12 hours.

List Assets

GET /v1/video/assets

Query param	Description
group_id	Filter by group (a real-human person). Omit to list your default Virtual group.
status	`active`, `processing`, or `failed` (comma-separated allowed).
name	Fuzzy name search.
page, limit	Pagination (default `page=1`, `limit=10`, max `limit=100`).
sort_by	`create_time`, `update_time`, or `group_id`.
sort_order	`asc` or `desc`.

Response `200`

{
  "object": "list",
  "items": [
    {
      "id": "asset-20260619150241-b8xd4",
      "name": "model-rachel-frontal",
      "url": "https://.../portrait.jpg?...",
      "asset_type": "Image",
      "group_id": "group-20260619145855-snq4q",
      "status": "active",
      "created_at": "2026-06-19T07:02:41Z",
      "updated_at": "2026-06-19T07:02:46Z"
    }
  ],
  "total_count": 1,
  "page_number": 1,
  "page_size": 10
}

Generate a Video From an Asset

Reference the asset with the asset://<asset_id> URI. Real-human assets are supported by Seedance 2.0 models only.

POST /v1/video/generations

Field	Type	Required	Description
model	`string`	Yes	`byteplus/seedance-2.0` or `byteplus/seedance-2.0-fast`.
content	`array`	Yes	Ordered list of `text` and `image_url` parts.

In the prompt, refer to assets positionally (e.g. "image 1"), not by ID.

Request

curl -X POST "https://api.pomex.ai/v1/video/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byteplus/seedance-2.0-fast",
    "content": [
      {"type": "text", "text": "The person in image 1 smiles and waves at the camera. Indoor, natural light, gentle push-in."},
      {"type": "image_url", "image_url": {"url": "asset://asset-20260619150241-b8xd4"}, "role": "reference_image"}
    ]
  }'

Response `200`

{
  "id": "cgt-20260619150458-96ncj",
  "object": "video.generation.task",
  "model": "byteplus/seedance-2.0-fast",
  "status": "queued"
}

Poll for the result

GET /v1/video/generations/{task_id}

{
  "id": "cgt-20260619150458-96ncj",
  "object": "video.generation.task",
  "status": "succeeded",
  "content": { "video_url": "https://.../output.mp4?..." }
}

status progresses queued → running → succeeded | failed. On success, content.video_url is a signed link valid for ≈24 hours — download and store it on your side.

Status Values

Object	Statuses
Session	`pending`
Asset	`processing` → `active` \| `failed`
Generation task	`queued` → `running` → `succeeded` \| `failed`

Error Handling

Errors return a standard envelope:

{ "error": { "message": "callback_url must be a valid https URL", "type": "invalid_request_error" } }

HTTP	`type`	When
400	`invalid_request_error`	Bad/missing parameters (see below).
401	`authentication_error`	Missing or invalid API key.
404	—	Resource not found.
502	`upstream_error`	Upstream provider failure.
503	—	Service temporarily unavailable; retry.

Common `400` messages

Message	Cause
callback_url is required	`callback_url` missing/empty.
callback_url must be a valid https URL	Non-HTTPS or malformed URL.
lang must be zh, en, or zh-Hant	Unsupported `lang`.
group id error	`group_id` does not belong to your organization.
status must be active, processing, or failed	Invalid List `status` filter.
body must be valid JSON	Malformed request body.

Notes & Limits

One person per group. Each group_id maps to a single verified person. Add more photos/styles of that person by uploading to the same group_id — no re-verification needed.
Image requirements. Public HTTPS direct image link; a single, clear, frontal face. Multi-face or mismatched-person images fail processing.
asset:// is Seedance 2.0 only. Older models do not accept real-human asset references.
Verification window. Have the end user complete the H5 scan promptly (≈30 minutes). Expired links require a new session.
Upstream rate limits (account-level): session create and result lookup ~3 QPS; list ~10 QPS; asset get ~100 QPS.
Billing. Session creation and asset list/get are not separately billed. Video generation is billed per the standard video pricing. Real-person verification billing is indicated by reqMeasureInfoValue in the callback.

End-to-End Quickstart (cURL)

export API_KEY="sk-..."
export API_BASE="https://api.pomex.ai"

# ① Create session
curl -sS -X POST "$API_BASE/v1/video/assets/sessions" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"callback_url":"https://yourapp.com/callback","lang":"en"}'
# → open the returned h5_link on a phone, complete the scan

# ③ Your callback receives: ?resultCode=10000&group_id=group-xxxx
export GROUP_ID="group-xxxx"

# ④ Upload a portrait of the same person
curl -sS -X POST "$API_BASE/v1/video/assets" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d "{\"url\":\"https://yourcdn.com/portrait.jpg\",\"asset_type\":\"Image\",\"group_id\":\"$GROUP_ID\"}"
export ASSET_ID="asset-xxxx"

# ⑤ Poll until active
curl -sS "$API_BASE/v1/video/assets/$ASSET_ID" -H "Authorization: Bearer $API_KEY"

# ⑥ Generate a video
curl -sS -X POST "$API_BASE/v1/video/generations" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d "{\"model\":\"byteplus/seedance-2.0-fast\",\"content\":[
        {\"type\":\"text\",\"text\":\"The person in image 1 waves and smiles.\"},
        {\"type\":\"image_url\",\"image_url\":{\"url\":\"asset://$ASSET_ID\"},\"role\":\"reference_image\"}]}"
# → poll GET /v1/video/generations/{task_id} until succeeded, read content.video_url

PomexAI · Real-Human Asset API · v1

Real-Human Asset API

Basics

Integration Flow

API Reference

Create Verification Session

Request

Response 200

Verification Callback (Your Endpoint)

Example redirect

Upload an Asset

Request

Response 200

Get an Asset

Response 200

List Assets

Response 200

Generate a Video From an Asset

Request

Response 200

Poll for the result

Status Values

Error Handling

Common 400 messages

Notes & Limits

End-to-End Quickstart (cURL)

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Common `400` messages