Omni V2V 视频编辑 API

Omni V2V 用自然语言编辑已有视频。接口接收 1 个源视频，还可以接收 1～2 张参考图，适合在尽量保留原视频动作、节奏和镜头结构的前提下修改画面内容。

本接口是异步任务：提交后先返回任务 ID，客户端轮询状态，完成后再下载最终视频。内部处理中的半成品不会作为成功结果返回。

可以编辑什么

Omni 是原生多模态视频模型，能够共同理解文本、图片和视频。常见用途包括：

人物与角色：参考人物图片保持外观特征；更换服装、发型或配饰；让参考人物进入原视频场景。
场景与背景：替换室内外环境、季节、天气、时间和背景陈设，同时尽量保留人物原有动作。
道具与商品：添加、替换、删除或隐藏物体；用商品参考图约束外形、颜色与材质。
视觉风格：真人转动漫、电影感、复古胶片、广告片、黏土动画、黑白片等整体风格转换。
光线与色彩：改变主光方向、冷暖色温、昼夜、雾、雨、雪、戏剧性照明与调色。
局部内容：修改标牌文字、让某个物体不可见，或只改变指定区域和元素。
镜头与节奏：描述镜头推进、横移、跟随、景别和特定时间点的事件；模型会结合源视频的运动信息进行编辑。
声音与音乐：可在提示词中要求环境音、背景音乐和音效。当前不应承诺修改源视频中的人物嗓音；官方说明语音编辑暂不支持。

参考图既可以是人物身份图，也可以是场景、道具、服装、商品或整体风格图。参考图用于约束编辑结果，并不等于首帧。

OpenAI / Sora 兼容接口

POST https://api.4allapi.com/v1/videos/edits
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_KEY

请求参数

参数	类型	必填	说明
`model`	string	是	使用 `omni_flash_v2v`；竖屏渠道可使用已开放的 portrait 变体
`prompt`	string	是	描述要改变什么，以及哪些内容必须保持不变
`video`	file	是	唯一的源视频文件。标准字段名是 `video`
`input_reference`	file	否	参考图片；重复该字段可传 1～2 张
`seconds`	integer/string	否	需要处理的秒数；不传时按源视频时长，最多按 10 秒处理；超过 10 自动按 10 处理
`resolution`	string	否	例如 `720p`；仅在当前上游模型与渠道支持时生效
`aspectRatio`	string	否	`16:9` 或 `9:16`；仅在当前模型支持时生效

参考图容错规则

可以不传参考图，也可以传 1 张或 2 张。
多于 2 张时只采用前 2 张，其余图片静默丢弃，不返回参数错误。
空文件、无法识别为图片的文件和超出单图限制的参考项会被忽略；只要源视频和提示词有效，任务仍可继续。
源视频必须通过 video 字段传入。旧版把源视频放在第一个 input_reference 的写法仅用于兼容，不建议新代码继续使用。
input_reference 可以重复，因此 Python requests 应使用元组列表，不能使用会覆盖同名键的普通字典。

cURL：1 个视频 + 2 张参考图

curl https://api.4allapi.com/v1/videos/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=omni_flash_v2v" \
  -F "prompt=Use reference image 1 for the character identity and reference image 2 for the red handbag. Replace the street with a rainy neon city at night. Keep the person's face, original body movement, camera path, timing and framing the same. Add natural rain ambience and soft cinematic music." \
  -F "video=@source.mp4;type=video/mp4" \
  -F "input_reference=@character.png;type=image/png" \
  -F "input_reference=@handbag.jpg;type=image/jpeg" \
  -F "seconds=8" \
  -F "resolution=720p"

只用 1 张参考图时，删除最后一个 input_reference 即可。完全不需要参考图时，可删除两个参考图字段。

Python 完整示例

import time
import requests

BASE_URL = "https://api.4allapi.com"
API_KEY = "sk-xxxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

prompt = (
    "Use reference image 1 as the character identity and reference image 2 "
    "as the prop. Change the location to a warm 1980s railway platform at "
    "sunset. Keep the original face, body motion, camera movement, timing and "
    "composition the same. Add subtle station ambience and restrained music."
)

with (
    open("source.mp4", "rb") as source_video,
    open("character.png", "rb") as character_image,
    open("prop.jpg", "rb") as prop_image,
):
    response = requests.post(
        f"{BASE_URL}/v1/videos/edits",
        headers=HEADERS,
        data={
            "model": "omni_flash_v2v",
            "prompt": prompt,
            "seconds": "8",
            "resolution": "720p",
        },
        files=[
            ("video", ("source.mp4", source_video, "video/mp4")),
            ("input_reference", ("character.png", character_image, "image/png")),
            ("input_reference", ("prop.jpg", prop_image, "image/jpeg")),
        ],
        timeout=180,
    )

response.raise_for_status()
task = response.json()
video_id = task["id"]

while task["status"] not in ("completed", "failed"):
    time.sleep(5)
    response = requests.get(
        f"{BASE_URL}/v1/videos/{video_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] == "failed":
    raise RuntimeError(task.get("error") or "video edit failed")

output = requests.get(
    f"{BASE_URL}/v1/videos/{video_id}/content",
    headers=HEADERS,
    timeout=300,
)
output.raise_for_status()
with open("edited.mp4", "wb") as file:
    file.write(output.content)

JSON URL 写法

源视频和参考图已经有可公开下载的 URL 时，也可使用 JSON：

curl https://api.4allapi.com/v1/videos/edits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "omni_flash_v2v",
    "prompt": "Make the jacket match reference image 1. Replace the background with reference image 2. Keep everything else the same.",
    "video": {"url": "https://example.com/source.mp4"},
    "input_reference": [
      {"image_url": "https://example.com/jacket.png"},
      {"image_url": "https://example.com/location.jpg"}
    ],
    "seconds": "8"
  }'

URL 必须能由服务器直接访问，并在任务处理期间保持有效。上传本地文件通常更稳定：源视频会先进入站内媒体中继，再交给视频模型处理。

Gemini 兼容传参

Gemini 风格的 multipart 请求仍使用 video 传源视频，参考图字段使用重复的 referenceImages：

curl "https://api.4allapi.com/v1beta/models/omni_flash_v2v:predictLongRunning?key=$API_KEY" \
  -F "prompt=Use reference image 1 for the person and reference image 2 for the room. Keep the motion and camera timing unchanged." \
  -F "video=@source.mp4;type=video/mp4" \
  -F "referenceImages=@person.png;type=image/png" \
  -F "referenceImages=@room.jpg;type=image/jpeg" \
  -F "durationSeconds=8" \
  -F "resolution=720p"

Gemini 原生 JSON 可在 instances[0].video 中传源视频，在 instances[0].referenceImages 中传最多两张图片；多余或无效参考图同样会被忽略。

查询与下载

提交任务后会得到类似响应：

{
  "id": "video_xxx",
  "object": "video",
  "model": "omni_flash_v2v",
  "status": "queued",
  "progress": 0
}

轮询任务：

curl https://api.4allapi.com/v1/videos/video_xxx \
  -H "Authorization: Bearer $API_KEY"

任务完成后下载最终视频：

curl https://api.4allapi.com/v1/videos/video_xxx/content \
  -H "Authorization: Bearer $API_KEY" \
  -o edited.mp4

下载接口仍需使用提交任务时的 4All API Key。不要把上游服务的密钥传给这个接口。

提示词写法

视频编辑和从零生成视频不同。编辑提示词越聚焦，越容易保留没有要求修改的内容。推荐结构：

Reference image 1: character identity and clothing reference.
Reference image 2: prop appearance and material reference.

Change: replace the daytime street with a rainy neon street at night; place the
red handbag from reference image 2 in the character's right hand.

Preserve: keep the character's face from reference image 1, original body motion,
walking direction, camera path, shot length, framing and natural physics the same.

Audio: light rain, distant traffic, restrained cinematic music; no dialogue.

建议遵循以下原则：

先写要改的内容，再写必须保留的内容。 例如“把背景改成雪夜；保持人物、动作、镜头和构图不变”。
参考图职责要单一。 明确“参考图 1 是人物”“参考图 2 是道具或场景”，避免两张图承担互相冲突的身份。
一次只安排少量主要修改。 复杂改造可拆成多次请求逐步验证。
使用可观察的描述。 写“把蓝色外套改成米白风衣”，不要只写“更高级、更有感觉”。
保留句不可省略。 只编辑局部时加入 Keep everything else the same，并列出最重要的脸、动作、镜头、时序和物理关系。
明确声音。 需要音乐、环境声或静音都直接写；不要依赖模型猜测。
时间点可用自然语言或时间码。 例如 After 3 seconds...，或 [0-3s] ...、[3-8s] ...。

能力边界

上传的视频建议不超过 10 秒；4All API 对本 V2V 模型的单次处理时长最多按 10 秒执行。
这是“重绘/编辑源视频”，不是精准像素级后期软件。复杂遮挡、快速运动、镜面、手指和密集小字仍可能出现不稳定结果。
官方说明目前不支持语音编辑；若源视频对白必须保持完全一致，建议后期重新合成原音轨。
参考图越清晰、主体越完整、角度越接近目标画面，人物和商品一致性通常越好。
提交内容和结果均受模型安全策略限制。

能力说明参考：Google Gemini Omni Flash 官方文档。本文接口字段、参考图数量和容错规则以 4All API 当前网关实现为准。