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/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/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://buble.ai/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://buble.ai/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://buble.ai/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);

Create Generations

On this page