> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # 视频背景移除 > 移除视频背景，返回透明或纯色背景的结果。 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)接口获取结果。 视频背景移除会将一个视频中的主体与背景分离。结果可使用透明背景或纯色背景，并以你选择的容器和编码格式返回。 ## 模型 * **poyo-ai/video-background-removal** — 移除一个视频的背景 ## 必填参数 * `video_url` (string)：源视频 URL。 ## 可选参数 * `output_container_and_codec` (string)：`mp4_h265`、`mp4_h264`、`webm_vp9`、`mov_h265`、`mov_proresks`、`mkv_h265`、`mkv_h264`、`mkv_vp9` 或 `gif`。 * `preserve_audio` (boolean)：是否保留源音轨。 * `background_color` (string)：`Transparent`、`Black`、`White`、`Gray`、`Red`、`Green`、`Blue`、`Yellow`、`Cyan`、`Magenta` 或 `Orange`。区分大小写。 ## 输出 任务完成后，`files` 中返回一个视频，`file_type: video`，按请求的 `output_container_and_codec` 编码。 ## 示例 * **透明背景，输出 WebM** — 设置 `video_url`、`background_color`、`output_container_and_codec`、`preserve_audio`。 * **绿幕，输出 MP4** — 设置 `video_url`、`background_color`、`output_container_and_codec`。 ## 注意事项 * 省略的可选字段使用供应商默认值。 * 如需透明结果，请将 `Transparent` 与支持 Alpha 通道的容器搭配使用，例如 `webm_vp9` 或 `mov_proresks`。 * PoYo 在提交前会读取视频时长。如果无法确定时长，提交会失败。 ## OpenAPI ````yaml zh/api-manual/tools-series/video-background-removal.json POST /api/generate/submit openapi: 3.0.0 info: title: 视频背景移除 description: 移除视频的背景。 version: 1.0.0 servers: - url: https://api.poyo.ai security: - BearerAuth: [] paths: /api/generate/submit: post: summary: 提交视频背景移除任务 operationId: submit_video_background_removal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: transparent: summary: 透明背景 WebM value: model: poyo-ai/video-background-removal input: video_url: https://example.com/dancer.mp4 background_color: Transparent output_container_and_codec: webm_vp9 preserve_audio: true green: summary: 绿幕 MP4 value: model: poyo-ai/video-background-removal input: video_url: https://example.com/dancer.mp4 background_color: Green output_container_and_codec: mp4_h264 responses: '200': description: 任务提交成功 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: 请求参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 未授权：API Key 无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object additionalProperties: false required: - model - input properties: model: type: string enum: - poyo-ai/video-background-removal description: 公开的模型标识。 callback_url: type: string format: uri description: 可选的 Webhook URL，用于接收任务完成或失败通知。 input: type: object additionalProperties: false required: - video_url properties: video_url: type: string format: uri description: 源视频 URL。必须是可公开访问的 HTTP 或 HTTPS URL。 output_container_and_codec: type: string enum: - mp4_h265 - mp4_h264 - webm_vp9 - mov_h265 - mov_proresks - mkv_h265 - mkv_h264 - mkv_vp9 - gif description: >- 输出容器和编码。当 `background_color` 为 `Transparent` 时，请选择支持透明度的格式，例如 `webm_vp9` 或 `mov_proresks`。省略时使用供应商默认值。 preserve_audio: type: boolean description: 是否保留源音轨。省略时使用供应商默认值。 background_color: type: string enum: - Transparent - Black - White - Gray - Red - Green - Blue - Yellow - Cyan - Magenta - Orange description: 放在主体后面的背景。取值区分大小写。省略时使用供应商默认值。 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1793176000-example status: type: string enum: - not_started - running - finished - failed example: not_started description: >- 任务状态。提交后立即返回时始终为 `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或 `callback_url` 获取。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` created_time: type: string format: date-time example: '2026-10-28T10:30:00' ErrorResponse: type: object required: - code - error properties: code: type: integer example: 400 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 error: type: object required: - message - type properties: message: type: string example: Invalid request parameters type: type: string example: validation_error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.