# 真人参考图

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

OfoxAI 允许你在普通的 `POST /v1/videos` 请求中直接提交已获授权的真人参考图。只需在顶层加入 `real_person: true`，再通过 `frame_images` 或 `input_references` 传图；Ofox 会在任务交给视频服务商前自动完成隐私保护预处理。

部分供应商要求含真人面部的参考图先在其平台完成素材入库与本人认证，例如 Seedance，对比说明见 [Seedance · 真人参考图](https://ofox.ai/zh/docs/develop/models/seedance#real-person)。使用 `real_person` 时无需预先完成这些步骤。

只能提交你依法有权且已获授权使用的图片。`real_person` 是处理指令，不是授权证明，也不会绕过 Ofox 或上游服务商的内容政策。

## 快速开始

```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": "让画面中的人物走过电影感夜市",
    "real_person": true,
    "input_references": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/person.jpg" }
      }
    ]
  }'
```

`real_person` 必须放在请求顶层。`frame_images` 或 `input_references` 中至少要有一张图片，而且这两个参考字段仍然互斥。具体结构与数量限制见[创建视频任务](https://ofox.ai/zh/docs/api/videos/create)。

## 提交后会发生什么

1. Ofox 校验并预处理所选参考字段中的每张图片。
2. 预处理后的请求被提交给所选视频服务商。
3. 服务商仍会执行自己的身份、反深度伪造和内容安全检查。

适合的输入通常可以进入正常的异步任务流程，但预处理不保证上游一定接受。少量图片仍可能触发上游真人审核或拒绝；被拒绝的任务不会计费。

## 图片仍触发真人审核时

让人物更容易被稳定识别，然后保持 `real_person: true` 重新提交：

- 保留一个清晰的主要人物，减少画面里其他可见人脸的数量；
- 裁剪或重新布局，让主要人脸足够大，不要贴近画面边缘；
- 优先使用清晰、正面、无遮挡且光线均匀的人脸；
- 尽量移除或裁掉背景人物、海报、屏幕、镜面和反光中的人脸；
- 避免极端角度、明显运动模糊、重阴影、口罩和大面积遮挡；
- 换用更高质量的原图，并简化过于拥挤的构图。

这些调整可以减少识别歧义，但不会覆盖服务商政策，也不保证一定通过。如果仍被拒绝，请更换另一张已获授权的参考图。

## 可直接修复的预处理错误

如果 Ofox 无法预处理输入图片，请求会返回 HTTP `400`，且 `error.code` 为 `"invalid_request"`。`error.message` 末尾会带有稳定原因短码：

| 原因短码 | 修复方式 |
|----------|----------|
| `bad_data_uri` | 修复格式错误的 `data:` URI 或 base64 内容 |
| `download_failed` | 确保 URL 可下载，且没有连接、超时或访问控制问题 |
| `unreachable` | 改用能返回成功 HTTP 状态的 URL |
| `not_image` | 提供支持且可解码的图片 |
| `too_large` | 减小文件、像素尺寸或单次处理的图片数量 |

完整错误对象与诊断方式见[视频 API 错误码](https://ofox.ai/zh/docs/api/videos/errors#real_person-图片预处理错误)。

## 相关文档

- [创建视频任务](https://ofox.ai/zh/docs/api/videos/create)
- [查询视频任务](https://ofox.ai/zh/docs/api/videos/retrieve)
- [视频 API 错误码](https://ofox.ai/zh/docs/api/videos/errors)