Real-person reference images with `real_person`

OfoxAI lets you submit an authorized real-person reference image directly in a normal POST /v1/videos request. Add the top-level real_person: true field and send the image through frame_images or input_references; Ofox applies privacy-preserving preprocessing before the task reaches the video provider.

This removes the vendor-side asset-enrollment step from your API integration. You do not need to create a Seedance real-person asset group, ask the subject to complete the provider’s verification flow, wait for the asset to become active, retrieve an Asset ID, and replace the image with an asset://... URI before the first request.

Only submit images that you are legally entitled and authorized to use. real_person is a processing instruction, not proof of consent, and it does not bypass Ofox or provider content policies.

Why the Ofox workflow is simpler

The official BytePlus Seedance 2.0 Video API documentation says that reference images or videos containing real human faces cannot be uploaded directly. Its documented route is an authorized real-person asset. The official private real-human asset guide describes real-person verification, asset consistency checks, an Active asset status, and an Asset URI for generation. The Volcano Ark guide further documents the invitation, authorization, upload, receipt, and Asset ID steps.

Step	Direct Seedance 2.0 API	Ofox Video API
Before the first request	Create an asset group, complete real-person verification and authorization, upload and validate the asset, then obtain its Asset ID	No vendor-side asset enrollment; use an image you are authorized to process
Reference value	An active authorized asset referenced as `asset://<asset_id>`	Your existing image URL or `data:` URI in `frame_images` or `input_references`
Request switch	Use the approved asset URI	Add top-level `"real_person": true`

Ofox simplifies the technical handoff, not the user’s responsibility for portrait rights and lawful use.

Quick start


curl -X POST https://api.ofox.ai/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "The person walks through a cinematic night market",
    "real_person": true,
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/person.jpg" }
      }
    ]
  }'

real_person belongs at the top level of the request. At least one image is required in either frame_images or input_references; the two reference fields remain mutually exclusive. See Create video for their exact shapes and limits.

What happens after submission

Ofox validates and preprocesses every image in the selected reference field.
The preprocessed request is submitted to the selected video provider.
The provider still applies its own identity, anti-deepfake, and content-safety checks.

Most suitable inputs can proceed through the normal asynchronous task flow, but preprocessing does not guarantee provider acceptance. A small minority of images may still trigger upstream real-person review or rejection. A rejected job is not charged.

If an image still triggers real-person review

Make the person easier to identify consistently, then submit the request again with real_person: true:

keep one clear primary person and reduce the number of other visible faces;
crop or rearrange the composition so the primary face is large enough and not near an edge;
prefer a clear, front-facing, unobstructed face with even lighting;
remove or crop background faces, posters, screens, mirrors, and reflections when possible;
avoid extreme angles, heavy motion blur, strong shadows, masks, and large occlusions;
use a higher-quality source image and simplify a crowded layout.

These adjustments reduce ambiguity; they do not override the provider’s policy or guarantee approval. If the provider still rejects the request, try a different authorized reference image.

Preprocessing errors you can fix directly

If Ofox cannot preprocess the supplied image, the request returns HTTP 400 with error.code: "invalid_request". The end of error.message contains a stable reason token:

Reason token	What to change
`bad_data_uri`	Fix the malformed `data:` URI or base64 payload
`download_failed`	Make the URL downloadable without a connection, timeout, or access-control failure
`unreachable`	Use a URL that returns a successful HTTP status
`not_image`	Supply a supported, decodable image
`too_large`	Reduce the file size, pixel dimensions, or number of images processed in one request

See Video API errors for the full error object and diagnostic guidance.

Real-person reference images with real_person