Create Generations

Use POST /api/v1/generations to create an asynchronous generation task.

Endpoint

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

Request body

Field	Type	Required	Description
model	string	Yes	Model key from /api/v1/media_models.
mode	string	Recommended	Public operation mode. Required when input shape is ambiguous.
prompt	string	No	Text instruction. Required by most modes.
image_urls	string array	No	Reference/source image URLs for supported modes.
start_frame	string	No	Start-frame image URL for frame-to-video modes.
end_frame	string	No	Optional end-frame image URL for supported modes.
video_urls	string array	No	Source video URLs for video-input modes.
audio_urls	string array	No	Source audio URLs for audio-input modes.
is_public	boolean	No	Defaults to false.
copy_protected	boolean	No	Defaults to true.

Model-specific controls returned by /api/v1/media_models, such as duration, resolution, aspect_ratio, output_format, web_search, or audio, are also sent directly at the request root.

Media input fields

Field	Type	Typical modes
image_urls	string array	image_to_image, reference_to_video
start_frame	string	frames_to_video
end_frame	string	frames_to_video with start/end frames
video_urls	string array	video_to_video, video_edit, video_extension
audio_urls	string array	Audio-input video modes

Internal fields are not accepted

Do not send input, options, or these internal fields: scene, sub_mode_id, subModeId, provider, mediaType, or media_type. Use the flat public fields and the public mode field instead.

Example: text to image

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"
  }'

Example: start-frame video

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 example

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 examples

SDK generation methods map to POST /api/v1/generations. Send the same flat public fields used by the HTTP API: model, mode, prompt/media URLs, and model-specific controls at the request root. Do not send internal fields such as input, options, scene, sub_mode_id, provider, mediaType, or media_type.

The snippets below assume you have already initialized the SDK client as shown in the Quickstart and imported the required language SDK types.

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"
)