视频背景移除 App API

使用 video-background-remover 可以从一个上传视频中移除背景，并返回适合剪辑、合成和透明视频工作流的前景视频。

App id

video-background-remover

在 /api/v1/apps/{app} 和 /api/v1/apps/{app}/generations 中使用这个 id。

输入参数

参数	类型	必填	默认值	可选值	说明
source_video	array	是	无	源文件 URL 数组	一个源视频 URL。支持 MP4、WebM、MOV、M4V，最大 500 MB。
refine_foreground_edges	boolean	否	true	true、false	尽可能优化主体边缘细节。
subject_is_person	boolean	否	true	true、false	当前景主体是人物时开启。

source_video 是数组类型，因为 app 媒体输入统一使用数组参数。该 app 只需要传入一个 URL。

计费

当前配置按输入视频时长计费，每秒 1 credit，向上取整，最低 1 credit。

Img2Vid 会在服务端根据提交的视频 URL 自动计算源视频时长。不要通过传递 duration 字段来控制计费。

输出

该 app 在 result.videos[].url 中返回视频 URL。当前工作流配置为适合合成使用的透明背景视频输出。

查询 app 参数

curl https://img2vid.net/api/v1/apps/video-background-remover \
  -H "Authorization: Bearer $BUBLE_API_KEY"

响应示例：

{
  "data": {
    "id": "video-background-remover",
    "input_parameters": [
      {
        "name": "source_video",
        "type": "array"
      },
      {
        "name": "refine_foreground_edges",
        "type": "boolean"
      },
      {
        "name": "subject_is_person",
        "type": "boolean"
      }
    ]
  }
}

创建生成任务

curl https://img2vid.net/api/v1/apps/video-background-remover/generations \
  -H "Authorization: Bearer $BUBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_video": ["https://example.com/source-video.mp4"],
    "refine_foreground_edges": true,
    "subject_is_person": true
  }'

响应示例：

{
  "data": {
    "id": "task_id",
    "status": "pending"
  }
}

查询结果

curl https://img2vid.net/api/v1/apps/video-background-remover/generations/task_id \
  -H "Authorization: Bearer $BUBLE_API_KEY"

成功响应结构：

{
  "data": {
    "id": "task_id",
    "status": "success",
    "result": {
      "videos": [
        {
          "url": "https://..."
        }
      ]
    }
  }
}

SDK 示例

下面的示例使用本页的 app id 和公开输入参数。片段假设你已经按快速开始初始化了 SDK client，并引入了对应语言需要的 SDK 类型。只发送 /api/v1/apps/{app} 返回的参数名；媒体参数需要传 URL。

JavaScript / TypeScript

const task = await buble.apps.generations.create('video-background-remover', {
  source_video: ['https://example.com/source.mp4'],
  refine_foreground_edges: true,
  subject_is_person: true,
});

const result = await buble.apps.generations.wait(
  'video-background-remover',
  task.data.id
);
console.log(result.data.result?.videos?.[0]?.url);

Python

task = client.apps.generations.create(
    "video-background-remover",
    source_video=["https://example.com/source.mp4"],
    refine_foreground_edges=True,
    subject_is_person=True,
)

result = client.apps.generations.wait("video-background-remover", task["data"]["id"])
print(result["data"]["result"]["videos"][0]["url"])

Go

task, err := client.Apps.Generations.Create(ctx, "video-background-remover", map[string]any{
	"source_video": []string{"https://example.com/source.mp4"},
	"refine_foreground_edges": true,
	"subject_is_person": true,
})
if err != nil {
	return err
}

result, err := client.Apps.Generations.Wait(ctx, "video-background-remover", task.Data.ID)

Rust

let mut body = serde_json::Map::new();
body.insert("source_video".to_string(), serde_json::json!(["https://example.com/source.mp4"]));
body.insert("refine_foreground_edges".to_string(), serde_json::json!(true));
body.insert("subject_is_person".to_string(), serde_json::json!(true));

let task = client.apps().generations().create("video-background-remover", body).await?;
let result = client
    .apps()
    .generations()
    .wait("video-background-remover", &task.data.id, WaitOptions::default())
    .await?;

Swift

let task = try await client.apps.generations.create(
    "video-background-remover",
    body: [
        "source_video": ["https://example.com/source.mp4"],
        "refine_foreground_edges": true,
        "subject_is_person": true
    ]
)

let result = try await client.apps.generations.wait("video-background-remover", task.data.id)

Dart / Flutter

final task = await client.apps.generations.create('video-background-remover', {
  'source_video': ['https://example.com/source.mp4'],
  'refine_foreground_edges': true,
  'subject_is_person': true,
});

final result = await client.apps.generations.wait('video-background-remover', task.data.id);

Elixir

{:ok, task} =
  Buble.Apps.Generations.create(client, "video-background-remover", %{
    source_video: ["https://example.com/source.mp4"],
    refine_foreground_edges: true,
    subject_is_person: true
  })

{:ok, result} = Buble.Apps.Generations.wait(client, "video-background-remover", task["data"]["id"])

Java

Envelope<AppGenerationTask> task = client.apps().generations().create(
        "video-background-remover",
        Map.of(
                "source_video", List.of("https://example.com/source.mp4"),
                "refine_foreground_edges", true,
                "subject_is_person", true));

Envelope<AppGenerationTask> result = client.apps().generations().wait(
        "video-background-remover",
        task.getData().getId());

.NET

var task = await client.Apps.Generations.CreateAsync(
    "video-background-remover",
    new Dictionary<string, object?>
    {
        ["source_video"] = new[] { "https://example.com/source.mp4" },
        ["refine_foreground_edges"] = true,
        ["subject_is_person"] = true
    });

var result = await client.Apps.Generations.WaitAsync(
    "video-background-remover",
    task!.Data!.Id!);

PHP

$task = $client->apps()->generations()->create('video-background-remover', [
    'source_video' => ['https://example.com/source.mp4'],
    'refine_foreground_edges' => true,
    'subject_is_person' => true,
]);

$result = $client->apps()->generations()->wait('video-background-remover', $task['data']['id']);

Ruby

task = client.apps.generations.create("video-background-remover", {
  "source_video" => ["https://example.com/source.mp4"],
  "refine_foreground_edges" => true,
  "subject_is_person" => true
})

result = client.apps.generations.wait("video-background-remover", task.dig("data", "id"))
puts result.dig("data", "result", "videos", 0, "url")