创建生成任务

使用 POST /api/v1/generations 创建异步生成任务。

Endpoint

POST /api/v1/generations
Content-Type: application/json

请求体

字段	类型	必填	说明
model	string	是	/api/v1/media_models 返回的模型 key。
mode	string	推荐	公开操作模式；当输入形态可能匹配多个 mode 时必须传。
prompt	string	否	文本指令；大多数 mode 都需要。
image_urls	string array	否	支持该输入的 mode 使用的参考图/源图片 URL。
start_frame	string	否	首帧图片 URL。
end_frame	string	否	支持首尾帧 mode 的尾帧图片 URL。
video_urls	string array	否	视频输入类 mode 使用的源视频 URL。
audio_urls	string array	否	音频输入类 mode 使用的源音频 URL。
is_public	boolean	否	默认 false。
copy_protected	boolean	否	默认 true。

/api/v1/media_models 返回的模型专属参数也直接放在请求体根层级，例如 duration、resolution、aspect_ratio、output_format、web_search 或 audio。

媒体输入字段

字段	类型	常见 mode
image_urls	string array	image_to_image、reference_to_video
start_frame	string	frames_to_video
end_frame	string	支持首尾帧的 frames_to_video
video_urls	string array	video_to_video、video_edit、video_extension
audio_urls	string array	支持音频输入的视频 mode

不接受内部字段

不要传递 input、options，也不要传递 scene、sub_mode_id、subModeId、provider、mediaType、media_type。公开接口请使用扁平字段和 mode。

示例：文生图

curl https://img2vid.net/api/v1/generations \
  -H "Authorization: Bearer $BUBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "mode": "text_to_image",
    "prompt": "A cinematic product photo of a premium ceramic coffee grinder on a walnut counter",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "output_format": "png"
  }'

示例：首帧视频

curl https://img2vid.net/api/v1/generations \
  -H "Authorization: Bearer $BUBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo3.1-fast",
    "mode": "frames_to_video",
    "prompt": "The camera slowly pushes in as morning light moves across the product surface, elegant cinematic motion",
    "start_frame": "https://example.com/product-start.png",
    "duration": "8s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

JavaScript 示例

const response = await fetch('https://img2vid.net/api/v1/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BUBLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'google/nano-banana-pro',
    mode: 'text_to_image',
    prompt: 'A clean editorial product image of a smart desk lamp',
    aspect_ratio: '1:1',
    resolution: '1K',
    output_format: 'png',
  }),
});

const { data, error } = await response.json();
if (error) throw new Error(error.message);
console.log(data.id);

SDK 示例

SDK 的生成任务创建方法对应 POST /api/v1/generations。请求仍使用与 HTTP API 相同的公开扁平字段：model、mode、prompt/媒体 URL，以及位于请求体根层级的模型专属参数。不要传递 input、options、scene、sub_mode_id、provider、mediaType 或 media_type 等内部字段。

下面的片段假设你已经按快速开始初始化了 SDK client，并引入了对应语言需要的 SDK 类型。

JavaScript / TypeScript

const task = await buble.generations.create({
  model: 'google/nano-banana',
  mode: 'text_to_image',
  prompt: 'A clean editorial product image of a smart desk lamp',
  aspect_ratio: '1:1',
  output_format: 'png',
});

Python

task = client.generations.create(
    model="google/nano-banana",
    mode="text_to_image",
    prompt="A clean editorial product image of a smart desk lamp",
    aspect_ratio="1:1",
    output_format="png",
)

Go

task, err := client.Generations.Create(ctx, &buble.CreateGenerationRequest{
	Model:  "google/nano-banana",
	Mode:   "text_to_image",
	Prompt: "A clean editorial product image of a smart desk lamp",
	Params: map[string]any{
		"aspect_ratio":  "1:1",
		"output_format": "png",
	},
})

Rust

let task = client.generations().create(
    CreateGenerationRequest::new("google/nano-banana")
        .mode("text_to_image")
        .prompt("A clean editorial product image of a smart desk lamp")
        .param("aspect_ratio", "1:1")?
        .param("output_format", "png")?,
).await?;

Swift

let task = try await client.generations.create(
    try CreateGenerationRequest(model: "google/nano-banana")
        .mode("text_to_image")
        .prompt("A clean editorial product image of a smart desk lamp")
        .param("aspect_ratio", "1:1")
        .param("output_format", "png")
)

Dart / Flutter

final task = await client.generations.create(
  CreateGenerationRequest(
    model: 'google/nano-banana',
    mode: 'text_to_image',
    prompt: 'A clean editorial product image of a smart desk lamp',
  ).withParam('aspect_ratio', '1:1').withParam('output_format', 'png'),
);

Elixir

{:ok, task} =
  Buble.Generations.create(client, %{
    model: "google/nano-banana",
    mode: "text_to_image",
    prompt: "A clean editorial product image of a smart desk lamp",
    aspect_ratio: "1:1",
    output_format: "png"
  })

Java

Envelope<GenerationTask> task = client.generations().create(
        CreateGenerationRequest.builder()
                .model("google/nano-banana")
                .mode("text_to_image")
                .prompt("A clean editorial product image of a smart desk lamp")
                .param("aspect_ratio", "1:1")
                .param("output_format", "png")
                .build());

.NET

var task = await client.Generations.CreateAsync(new CreateGenerationRequest
{
    Model = "google/nano-banana",
    Mode = "text_to_image",
    Prompt = "A clean editorial product image of a smart desk lamp"
}.WithParam("aspect_ratio", "1:1").WithParam("output_format", "png"));

PHP

$task = $client->generations()->create(
    CreateGenerationRequest::make(
        model: 'google/nano-banana',
        mode: 'text_to_image',
        prompt: 'A clean editorial product image of a smart desk lamp',
    )->withParam('aspect_ratio', '1:1')
     ->withParam('output_format', 'png')
);

Ruby

task = client.generations.create(
  model: "google/nano-banana",
  mode: "text_to_image",
  prompt: "A clean editorial product image of a smart desk lamp",
  aspect_ratio: "1:1",
  output_format: "png"
)