Using files

Método: media.upload

Cria uma File.

Endpoint

upload de uri, para solicitações de upload de mídia:
`post
https://generativelanguage.googleapis.com/upload/v1beta/files

  • URI de metadados, para solicitações somente de metadados:
    POST https://generativelanguage.googleapis.com/v1beta/filesO URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Campos
file object (File)

Opcional. Metadados do arquivo a ser criado.

Exemplo de solicitação

Imagem

Python

myfile = genai.upload_file(media / "Cajun_instruments.jpg")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content(
    [myfile, "\n\n", "Can you tell me about the instruments in this photo?"]
)
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);
// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this image.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

Áudio

Python

myfile = genai.upload_file(media / "sample.mp3")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content([myfile, "Describe this audio clip"])
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/samplesmall.mp3`,
  {
    mimeType: "audio/mp3",
    displayName: "Audio sample",
  },
);

let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  process.stdout.write(".");
  // Sleep for 10 seconds
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  // Fetch the file from the API again
  file = await fileManager.getFile(uploadResult.file.name);
}

if (file.state === FileState.FAILED) {
  throw new Error("Audio processing failed.");
}

// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this audio clip.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

Texto

Python

myfile = genai.upload_file(media / "poem.txt")
print(f"{myfile=}")

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content(
    [myfile, "\n\n", "Can you add a few more lines to this poem?"]
)
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(`${mediaPath}/a11.txt`, {
  mimeType: "text/plain",
  displayName: "Apollo 11",
});
// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Transcribe the first few sentences of this document.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

Vídeo

Python

import time

# Video clip (CC BY 3.0) from https://peach.blender.org/download/
myfile = genai.upload_file(media / "Big_Buck_Bunny.mp4")
print(f"{myfile=}")

# Videos need to be processed before you can use them.
while myfile.state.name == "PROCESSING":
    print("processing video...")
    time.sleep(5)
    myfile = genai.get_file(myfile.name)

model = genai.GenerativeModel("gemini-1.5-flash")
result = model.generate_content([myfile, "Describe this video clip"])
print(f"{result.text=}")

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager, FileState } from "@google/generative-ai/server";
// import { GoogleGenerativeAI } from "@google/generative-ai";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/Big_Buck_Bunny.mp4`,
  {
    mimeType: "video/mp4",
    displayName: "Big Buck Bunny",
  },
);

let file = await fileManager.getFile(uploadResult.file.name);
while (file.state === FileState.PROCESSING) {
  process.stdout.write(".");
  // Sleep for 10 seconds
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  // Fetch the file from the API again
  file = await fileManager.getFile(uploadResult.file.name);
}

if (file.state === FileState.FAILED) {
  throw new Error("Video processing failed.");
}

// View the response.
console.log(
  `Uploaded file ${uploadResult.file.displayName} as: ${uploadResult.file.uri}`,
);

const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
const result = await model.generateContent([
  "Tell me about this video.",
  {
    fileData: {
      fileUri: uploadResult.file.uri,
      mimeType: uploadResult.file.mimeType,
    },
  },
]);
console.log(result.response.text());

Corpo da resposta

Resposta para media.upload.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

.
Campos
file object (File)

Metadados do arquivo criado.

Representação JSON
{
  "file": {
    object (File)
  }
}

Método: files.get

Recebe os metadados para o File especificado.

Endpoint

recebe https://generativelanguage.googleapis.com/v1beta/{name=files/*}

Parâmetros de caminho

name string

Obrigatório. O nome da File a ser recebida. Exemplo: files/abc-123. Ele assume o formato files/{file}.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Exemplo de solicitação

Python

myfile = genai.upload_file(media / "poem.txt")
file_name = myfile.name
print(file_name)  # "files/*"

myfile = genai.get_file(file_name)
print(myfile)

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResponse = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Get the previously uploaded file's metadata.
const getResponse = await fileManager.getFile(uploadResponse.file.name);

// View the response.
console.log(
  `Retrieved file ${getResponse.displayName} as ${getResponse.uri}`,
);

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta conterá uma instância de File.

Método: files.list

Lista os metadados de Files pertencentes ao projeto solicitante.

Endpoint

recebe https://generativelanguage.googleapis.com/v1beta/files

Parâmetros de consulta

pageSize integer

Opcional. Número máximo de Files a serem retornados por página. Se não for especificado, o padrão será 10. O pageSize máximo é 100.

pageToken string

Opcional. Um token de página de uma chamada files.list anterior.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Exemplo de solicitação

Python

print("My files:")
for f in genai.list_files():
    print("  ", f.name)

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const listFilesResponse = await fileManager.listFiles();

// View the response.
for (const file of listFilesResponse.files) {
  console.log(`name: ${file.name} | display name: ${file.displayName}`);
}

Corpo da resposta

Resposta para files.list.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

.
Campos
files[] object (File)

Lista de Files.

nextPageToken string

Um token que pode ser enviado como um pageToken para uma chamada files.list subsequente.

Representação JSON
{
  "files": [
    {
      object (File)
    }
  ],
  "nextPageToken": string
}

Método: files.delete

Exclui o File.

Endpoint

excluir https://generativelanguage.googleapis.com/v1beta/{name=files/*}

Parâmetros de caminho

name string

Obrigatório. O nome do File a ser excluído. Exemplo: files/abc-123. Ele assume o formato files/{file}.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Exemplo de solicitação

Python

myfile = genai.upload_file(media / "poem.txt")

myfile.delete()

try:
    # Error.
    model = genai.GenerativeModel("gemini-1.5-flash")
    result = model.generate_content([myfile, "Describe this file."])
except google.api_core.exceptions.PermissionDenied:
    pass

Node.js

// Make sure to include these imports:
// import { GoogleAIFileManager } from "@google/generative-ai/server";
const fileManager = new GoogleAIFileManager(process.env.API_KEY);

const uploadResult = await fileManager.uploadFile(
  `${mediaPath}/jetpack.jpg`,
  {
    mimeType: "image/jpeg",
    displayName: "Jetpack drawing",
  },
);

// Delete the file.
await fileManager.deleteFile(uploadResult.file.name);

console.log(`Deleted ${uploadResult.file.displayName}`);

Corpo da resposta

Se a solicitação for concluída, o corpo da resposta estará vazio.

Recurso REST: files

Recurso: File

Um arquivo enviado para a API.

Representação JSON
{
  "name": string,
  "displayName": string,
  "mimeType": string,
  "sizeBytes": string,
  "createTime": string,
  "updateTime": string,
  "expirationTime": string,
  "sha256Hash": string,
  "uri": string,
  "state": enum (State),
  "error": {
    object (Status)
  },

  // Union field metadata can be only one of the following:
  "videoMetadata": {
    object (VideoMetadata)
  }
  // End of list of possible types for union field metadata.
}
.
Campos
name string

Imutável. Identificador. O nome do recurso File. O ID (nome sem o prefixo "files/") pode ter até 40 caracteres alfanuméricos em letras minúsculas ou traços (-). Ele não pode começar nem terminar com um traço. Se o nome estiver vazio na criação, um nome exclusivo será gerado. Exemplo: files/123-456

displayName string

Opcional. O nome de exibição legível para o File. O nome de exibição não pode ter mais de 512 caracteres, incluindo espaços. Exemplo: "Imagem de boas-vindas"

mimeType string

Apenas saída. Tipo MIME do arquivo.

sizeBytes string (int64 format)

Apenas saída. Tamanho do arquivo em bytes.

createTime string (Timestamp format)

Apenas saída. O carimbo de data/hora de quando o File foi criado.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

Apenas saída. O carimbo de data/hora de quando o File foi atualizado pela última vez.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

expirationTime string (Timestamp format)

Apenas saída. Carimbo de data/hora de quando o File será excluído. Defina apenas se o File estiver programado para expirar.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".

sha256Hash string (bytes format)

Apenas saída. O hash SHA-256 dos bytes enviados.

Uma string codificada em base64.

uri string

Apenas saída. O URI de File.

state enum (State)

Apenas saída. Estado de processamento do arquivo.

error object (Status)

Apenas saída. Status de erro se o processamento do arquivo falhar.

Campo de união metadata. Metadados do arquivo. metadata pode ser apenas de um dos tipos a seguir:
videoMetadata object (VideoMetadata)

Apenas saída. Metadados de um vídeo.

VideoMetadata

Metadados de um vídeo File.

Representação JSON
{
  "videoDuration": string
}
.
Campos
videoDuration string (Duration format)

Duração do vídeo.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

Estado

Estados para o ciclo de vida de um arquivo.

Enums
STATE_UNSPECIFIED O valor padrão. Esse valor será usado se o estado for omitido.
PROCESSING O arquivo está sendo processado e ainda não pode ser usado para inferência.
ACTIVE O arquivo é processado e fica disponível para inferência.
FAILED Falha ao processar o arquivo.

Status

O tipo Status define um modelo de erro lógico que é adequado a diferentes ambientes de programação, incluindo APIs REST e RPC. É usado por gRPC (em inglês). Cada mensagem Status contém três partes de dados: código do erro, mensagem de erro e detalhes do erro.

É possível descobrir mais sobre esse modelo de erro e como trabalhar com ele no Guia de design de API.

Representação JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
.
Campos
code integer

O código de status, que precisa ser um valor de enumeração de google.rpc.Code.

message string

Uma mensagem de erro em inglês para o desenvolvedor. Qualquer mensagem de erro para o usuário precisa ser localizada e enviada no campo google.rpc.Status.details, ou localizada pelo cliente.

details[] object

Uma lista de mensagens com os detalhes do erro. Há um conjunto comum de tipos de mensagens para as APIs usarem.

Um objeto contendo campos de um tipo arbitrário. Um campo adicional "@type" contém uma URI que identifica o tipo. Exemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.