# SEE2AI 视频替换

> Replace the person, product, or background in one source video using one to nine ordered reference images.

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_video_replacement_v1`

**认证方式**: Bearer Token (租户 API Key)

### Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/v1/actions/see2ai_video_replacement_v1` | Submit the standard action request. |

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台标准化封装后的接口，**参数格式与任何上游 API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考其他文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "additionalProperties": false,
  "description": "One source video and reference views produce one replacement result.",
  "examples": [
    {
      "duration": 5,
      "generate_audio": true,
      "image_urls": [
        "https://media.example/front.png",
        "https://media.example/side.png"
      ],
      "mode": "product",
      "person_consent_confirmed": false,
      "prompt": "Keep the camera motion unchanged.",
      "quality": "standard",
      "resolution": "1080p",
      "video_url": "https://media.example/source.mp4"
    }
  ],
  "properties": {
    "video_url": {
      "description": "Public HTTP(S) source video URL; media is checked before submission.",
      "title": "Video Url",
      "type": "string"
    },
    "image_urls": {
      "description": "One to nine ordered public HTTP(S) reference images for one result.",
      "items": {
        "type": "string"
      },
      "maxItems": 9,
      "minItems": 1,
      "title": "Image Urls",
      "type": "array"
    },
    "mode": {
      "description": "The subject to replace while preserving the rest of the video.",
      "enum": [
        "person",
        "product",
        "background"
      ],
      "title": "Mode",
      "type": "string"
    },
    "prompt": {
      "default": "",
      "description": "Optional editing constraints, preserved as supplied.",
      "title": "Prompt",
      "type": "string"
    },
    "quality": {
      "default": "standard",
      "description": "Generation tier; fast supports 480p and 720p.",
      "enum": [
        "standard",
        "fast"
      ],
      "title": "Quality",
      "type": "string"
    },
    "resolution": {
      "default": "1080p",
      "description": "Output resolution; 1080p requires standard quality.",
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "title": "Resolution",
      "type": "string"
    },
    "duration": {
      "anyOf": [
        {
          "maximum": 15,
          "minimum": 4,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional target output duration in whole seconds, from 4 to 15.",
      "title": "Duration"
    },
    "generate_audio": {
      "default": true,
      "description": "Whether to generate audio with the result; omitted means true.",
      "title": "Generate Audio",
      "type": "boolean"
    },
    "person_consent_confirmed": {
      "default": false,
      "description": "Explicit consent evidence for real people in the material. Required for person replacement; for product or background replacement, true runs footage with real people through verified asset handling, and false or omitted keeps standard replacement.",
      "title": "Person Consent Confirmed",
      "type": "boolean"
    },
    "model": {
      "anyOf": [
        {
          "enum": [
            "seedance-2.0",
            "seedance-2.5"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional video model; omit it to keep seedance-2.0. seedance-2.5 supports standard quality at 480p or 720p and keeps the source video's length, so omit duration.",
      "title": "Model"
    }
  },
  "required": [
    "video_url",
    "image_urls",
    "mode"
  ],
  "title": "ActionInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `video_url` | string | ✅ 是 | `-` | Public HTTP(S) source video URL; media is checked before submission. |
| `image_urls` | array | ✅ 是 | `-` | One to nine ordered public HTTP(S) reference images for one result. |
| `mode` | string enum | ✅ 是 | `-` | The subject to replace while preserving the rest of the video. |
| `prompt` | string | ❌ 否 | `` | Optional editing constraints, preserved as supplied. |
| `quality` | string enum | ❌ 否 | `standard` | Generation tier; fast supports 480p and 720p. |
| `resolution` | string enum | ❌ 否 | `1080p` | Output resolution; 1080p requires standard quality. |
| `duration` | integer / null | ❌ 否 | `-` | Optional target output duration in whole seconds, from 4 to 15. |
| `generate_audio` | boolean | ❌ 否 | `True` | Whether to generate audio with the result; omitted means true. |
| `person_consent_confirmed` | boolean | ❌ 否 | `False` | Explicit consent evidence for real people in the material. Required for person replacement; for product or background replacement, true runs footage with real people through verified asset handling, and false or omitted keeps standard replacement. |
| `model` | string enum / null | ❌ 否 | `-` | Optional video model; omit it to keep seedance-2.0. seedance-2.5 supports standard quality at 480p or 720p and keeps the source video's length, so omit duration. |

## 📤 输出结果 (Output Schema)

```json
{
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入消耗的词元数量",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出消耗的词元数量",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总消耗的词元数量",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "const": "see2ai-video-replacement-v1",
      "default": "see2ai-video-replacement-v1",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "const": "see2ai",
      "default": "see2ai",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "task_id": {
      "description": "Opaque task identity used for status polling.",
      "title": "Task Id",
      "type": "string"
    },
    "status": {
      "enum": [
        "running",
        "success",
        "failed"
      ],
      "title": "Status",
      "type": "string"
    },
    "result_urls": {
      "description": "Durable video references after successful settlement.",
      "items": {
        "type": "string"
      },
      "title": "Result Urls",
      "type": "array"
    },
    "video_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Durably preserved replacement video after settlement.",
      "title": "Video Url"
    },
    "diagnostic_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Durably preserved diagnostic artifact after settlement.",
      "title": "Diagnostic Url"
    },
    "retryable": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Retryable"
    },
    "retry_after_seconds": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Retry After Seconds"
    },
    "error_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Stable SEE2AI failure code when the terminal reason is known.",
      "title": "Error Code"
    },
    "error_message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Brand-safe failure or recovery guidance.",
      "title": "Error Message"
    },
    "reason_category": {
      "anyOf": [
        {
          "enum": [
            "content_safety",
            "deterministic"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Reason Category"
    },
    "warnings": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Non-blocking optimization suggestions retained with the original request.",
      "title": "Warnings"
    }
  },
  "required": [
    "task_id",
    "status"
  ],
  "title": "VideoReplacementStatusOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入消耗的词元数量 |
| `output_tokens` | integer | 输出消耗的词元数量 |
| `total_tokens` | integer | 总消耗的词元数量 |
| `model` | string |  |
| `source` | string |  |
| `cost_points` | integer / null | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `task_id` | string | Opaque task identity used for status polling. |
| `status` | string enum |  |
| `result_urls` | array | Durable video references after successful settlement. |
| `video_url` | string / null | Durably preserved replacement video after settlement. |
| `diagnostic_url` | string / null | Durably preserved diagnostic artifact after settlement. |
| `retryable` | boolean / null |  |
| `retry_after_seconds` | integer / null |  |
| `error_code` | string / null | Stable SEE2AI failure code when the terminal reason is known. |
| `error_message` | string / null | Brand-safe failure or recovery guidance. |
| `reason_category` | string enum / null |  |
| `warnings` | array / null | Non-blocking optimization suggestions retained with the original request. |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_video_replacement_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "duration": 5,
  "generate_audio": true,
  "image_urls": [
    "https://media.example/front.png",
    "https://media.example/side.png"
  ],
  "mode": "product",
  "person_consent_confirmed": false,
  "prompt": "Keep the camera motion unchanged.",
  "quality": "standard",
  "resolution": "1080p",
  "video_url": "https://media.example/source.mp4"
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_video_replacement_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "duration": 5,
  "generate_audio": true,
  "image_urls": [
    "https://media.example/front.png",
    "https://media.example/side.png"
  ],
  "mode": "product",
  "person_consent_confirmed": false,
  "prompt": "Keep the camera motion unchanged.",
  "quality": "standard",
  "resolution": "1080p",
  "video_url": "https://media.example/source.mp4"
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> Measured from the mean source/output duration and selected quality and resolution; maximum CNY 95.220.

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `400` | Invalid replacement media or parameters | 请稍后重试 |
| `402` | Insufficient balance for the full task ceiling | 请稍后重试 |
| `503` | Replacement submission or settlement is temporarily unavailable | 请稍后重试 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_video_replacement_v1
**最后更新**: 2026-03-23