> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Veo Objects API 对接说明

> Veo Video Generation 集成指南 - XHuoAPI

本文将介绍 Veo Objects API 的对接说明。该接口用于对一段已经生成的 Veo 视频进行**物体增加或删除**操作（基于蒙版的局部重绘）。

## 申请流程

要使用 API，需要先到 Veo 服务对应页面申请。如果你尚未登录或注册，会自动跳转到登录页面。

## 基本使用

调用本接口需要传入下列参数：

* `video_id`（必填）：来源视频的任务 ID。**不能**是 `/veo/extend` 的输出视频。
* `action`（必填）：操作类型，`insert` 或 `remove`。
* `prompt`：
  * `action=insert`：**必填**，描述要加入的物体。
  * `action=remove`：选填，描述要移除的内容（主要用于日志记录，实际擦除区域由 `image_mask` 决定）。
* `image_mask`：
  * `action=insert`：选填。如果不传，AI 会自动决定插入位置；如果传入，则在白色像素区域插入。
  * `action=remove`：**必填**，白色像素区域为要擦除的对象。

`image_mask` 接受两种格式：

1. 一个**公开可访问的 HTTP(S) 图片地址**（推荐）。
2. **base64 编码的 JPEG 字符串**，可以带 `data:image/jpeg;base64,` 前缀，也可以是裸 base64。

请求示例（插入物体，不传蒙版，让 AI 自动定位）：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/veo/objects' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "video_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
    "action": "insert",
    "prompt": "add a flying pig with black wings"
  }'
```

请求示例（按蒙版移除物体）：

```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/veo/objects' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "video_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
    "action": "remove",
    "image_mask": "https://example.com/mask.jpg",
    "prompt": "remove the white cloud"
  }'
```

返回结果结构与 `/veo/videos` 相同。

## 计费说明

* `action=insert` 或 `remove`：1.50 Credit / 次。

## 异步回调

接口支持异步模式，传入 `callback_url` 即可在任务完成后通过 POST 请求回调结果。