# Real-person reference images

Source: https://ofox.io/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 `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.io/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.io/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, and `input_references` must contain at least one image. `real_person` does not support `frame_images` (first-frame or first/last-frame requests); sending both returns `400 invalid_request`, because the preprocessed image carries visible markings and would appear in the output video when used as a first or last frame. For real-person references, put all images in `input_references`. For the exact structure and count limits, see [Create video task](https://ofox.io/docs/api/videos/create).

## What happens after submission

1. Ofox validates and preprocesses every image in `input_references`.
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.io/docs/api/videos/errors#real_person-preprocessing-errors).

## Related docs

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