Upload Files

Use POST /api/v1/files to upload source assets before calling image-to-image, image-to-video, video-to-video, or audio-assisted modes.

Endpoint

POST /api/v1/files
Content-Type: multipart/form-data

Form fields

Field	Type	Required	Description
file	File	Yes	Image, video, or audio file.
file_type	string	No	image, video, or audio. Inferred from MIME type if omitted.
model	string	No	Optional model key for model-specific validation.
mode	string	No	Optional public mode for mode-specific validation.

If model and mode are provided, Img2Vid validates file type, size, and format against that model mode. If omitted, Img2Vid applies default upload limits.

Default upload limits

Type	Default max size
Image	30 MB
Video	100 MB
Audio	50 MB

Model-specific limits can be stricter. Check the relevant model page under Video Models or Image Models before uploading production assets.

Upload an image for image-to-image

curl https://img2vid.net/api/v1/files \
  -H "Authorization: Bearer $BUBLE_API_KEY" \
  -F "file=@./source.png" \
  -F "file_type=image" \
  -F "model=google/nano-banana-pro" \
  -F "mode=image_to_image"

Response

{
  "data": {
    "object": "file",
    "provider": "r2",
    "url": "https://...",
    "key": "api/image/xxx.png",
    "file_type": "image",
    "content_type": "image/png",
    "size": 123456,
    "filename": "source.png"
  }
}

Pass the returned data.url into image_urls, start_frame, end_frame, video_urls, or audio_urls depending on the selected mode.

SDK examples

SDK uploads map to POST /api/v1/files. Provide model and mode when you know the target workflow so Img2Vid can apply model-specific validation before generation.

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 uploaded = await buble.files.upload('./reference.png', {
  file_type: 'image',
  model: 'google/nano-banana',
  mode: 'image_to_image',
});

const imageUrl = uploaded.data.url;

Python

uploaded = client.files.upload(
    "reference.png",
    file_type="image",
    model="google/nano-banana",
    mode="image_to_image",
)

image_url = uploaded["data"]["url"]

Go

uploaded, err := client.Files.Upload(
	ctx,
	buble.FileFromPath("./reference.png"),
	buble.WithFileType("image"),
	buble.WithUploadModel("google/nano-banana"),
	buble.WithUploadMode("image_to_image"),
)
if err != nil {
	return err
}

imageURL := uploaded.Data.URL

Rust

use buble::{FileUpload, UploadOptions};

let uploaded = client.files().upload(
    FileUpload::from_path("./reference.png"),
    UploadOptions::new()
        .file_type("image")
        .model("google/nano-banana")
        .mode("image_to_image"),
).await?;

let image_url = uploaded.data.url;

Swift

let uploaded = try await client.files.upload(
    .fromFileURL(URL(fileURLWithPath: "reference.png"), contentType: "image/png"),
    options: UploadOptions(
        fileType: "image",
        model: "google/nano-banana",
        mode: "image_to_image"
    )
)

let imageURL = uploaded.data.url

Dart / Flutter

final uploaded = await client.files.upload(
  FileUpload.fromPath('reference.png', contentType: 'image/png'),
  options: const UploadOptions(
    fileType: 'image',
    model: 'google/nano-banana',
    mode: 'image_to_image',
  ),
);

final imageUrl = uploaded.data.url;

Elixir

{:ok, uploaded} =
  Buble.Files.upload(client, {:path, "reference.png"},
    file_type: "image",
    model: "google/nano-banana",
    mode: "image_to_image"
  )

image_url = uploaded["data"]["url"]

Java

Envelope<UploadedFile> uploaded = client.files().upload(
        FileUpload.fromPath(Path.of("reference.png")),
        UploadOptions.builder()
                .fileType("image")
                .model("google/nano-banana")
                .mode("image_to_image")
                .build());

String imageUrl = uploaded.getData().getUrl();

.NET

var uploaded = await client.Files.UploadAsync(
    FileUpload.FromPath("reference.png", "image/png"),
    new UploadOptions
    {
        FileType = "image",
        Model = "google/nano-banana",
        Mode = "image_to_image"
    });

var imageUrl = uploaded!.Data!.Url;

PHP

use Buble\Files\FileUpload;
use Buble\Files\UploadOptions;

$uploaded = $client->files()->upload(
    FileUpload::fromPath('reference.png', 'image/png'),
    new UploadOptions(
        fileType: 'image',
        model: 'google/nano-banana',
        mode: 'image_to_image'
    )
);

$imageUrl = $uploaded['data']['url'];

Ruby

uploaded = client.files.upload(
  Buble::FileUpload.from_path("reference.png", content_type: "image/png"),
  file_type: "image",
  model: "google/nano-banana",
  mode: "image_to_image"
)

image_url = uploaded.dig("data", "url")