# Real-person reference images

Source: https://ofox.ai/docs/api/videos/real-person

OfoxAI lets you submit authorized real-person reference images directly in a normal `POST /v1/videos` request. Just add `real_person: true` at the top level and pass the image through `frame_images` or `input_references`; Ofox automatically applies privacy-preserving preprocessing before the task is handed to the video provider.

Some providers require reference images containing real human faces to go through asset enrollment and identity verification on their platform first, for example Seedance; see [Seedance · Real-person reference images](https://ofox.ai/docs/develop/models/seedance#real-person) for a comparison. With `real_person`, you do not need to complete these steps in advance.

Only submit images you are legally entitled and authorized to use. `real_person` is a processing instruction, not proof of authorization, and it does not bypass the content policies of Ofox or upstream providers.

## Quickstart

```bash
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 in the frame walks through a cinematic night market",
    "real_person": true,
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/person.jpg" }
      }
    ]
  }'
```

`real_person` must be at the top level of the request. At least one image is required in `frame_images` or `input_references`, and the two reference fields remain mutually exclusive. For the exact structure and count limits, see [Create video task](https://ofox.ai/docs/api/videos/create).

## What happens after submission

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

Suitable inputs can usually proceed through the normal asynchronous task flow, but preprocessing does not guarantee upstream acceptance. A small number of images may still trigger upstream real-person review or rejection; rejected tasks are not charged.

## If an image still triggers real-person review

Make the person easier to identify consistently, then resubmit with `real_person: true`:

- Keep one clear primary person and reduce the number of other visible faces in the frame;
- Crop or rearrange the composition so the primary face is large enough and not close to the edge;
- Prefer a clear, front-facing, unobstructed face with even lighting;
- Remove or crop out faces in background people, posters, screens, mirrors, and reflections where possible;
- Avoid extreme angles, noticeable motion blur, heavy shadows, masks, and large occlusions;
- Switch to a higher-quality source image and simplify overly crowded compositions.

These adjustments reduce ambiguity in identification, but they do not override provider policy or guarantee acceptance. If the image is still rejected, use a different authorized reference image.

## Preprocessing errors you can fix directly

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

| Reason code | How to fix |
|----------|----------|
| `bad_data_uri` | Fix the malformed `data:` URI or base64 content |
| `download_failed` | Make sure the URL is downloadable without connection, timeout, or access-control problems |
| `unreachable` | Use a URL that returns a successful HTTP status |
| `not_image` | Provide a supported, decodable image |
| `too_large` | Reduce the file size, pixel dimensions, or number of images processed per request |

For the full error object and diagnostics, see [Video API error codes](https://ofox.ai/docs/api/videos/errors#real_person-preprocessing-errors).

## Related docs

- [Create video task](https://ofox.ai/docs/api/videos/create)
- [Get video task](https://ofox.ai/docs/api/videos/retrieve)
- [Video API error codes](https://ofox.ai/docs/api/videos/errors)