上传文件

使用 POST /api/v1/files 在图生图、图生视频、视频生视频或音频辅助生成前上传源素材。

Endpoint

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

表单字段

字段	类型	必填	说明
file	File	是	图片、视频或音频文件。
file_type	string	否	image、video 或 audio。不传时按 MIME 类型推断。
model	string	否	可选模型 key，用于模型级校验。
mode	string	否	可选公开 mode，用于 mode 级校验。

如果传入 model 和 mode，Buble 会按照该模型模式校验文件类型、大小和格式。如果不传，则使用默认上传限制。

默认上传限制

类型	默认最大大小
图片	30 MB
视频	100 MB
音频	50 MB

模型专属限制可能更严格。生产上传前建议先查看 Video Models 或 Image Models 下的对应模型页面。

上传图生图素材

curl https://buble.ai/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"

响应

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

根据所选 mode，把返回的 data.url 传入 image_urls、start_frame、end_frame、video_urls 或 audio_urls。

SDK 示例

SDK 上传方法对应 POST /api/v1/files。如果已经知道后续要调用的模型和 mode，建议在上传时传入 model 与 mode，这样 Buble 可以提前做模型级文件校验。

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

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