Using files

Método: media.upload

Crea un File.

Extremo

URI de carga, para solicitudes de carga de contenido multimedia:
`post
. https://generativelanguage.googleapis.com/upload/v1beta/files
.
  • URI de metadatos, para solicitudes solo de metadatos:
    POST https://generativelanguage.googleapis.com/v1beta/filesLa URL usa la sintaxis de transcodificación gRPC.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Campos
file object (File)

Opcional. Metadatos del archivo que se creará.

Ejemplo de solicitud

Imagen

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());

Audio

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());

Video

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());

Cuerpo de la respuesta

La respuesta para media.upload.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Campos
file object (File)

Metadatos del archivo creado.

Representación JSON
{
  "file": {
    object (File)
  }
}

Método: files.get

Obtiene los metadatos del File determinado.

Extremo

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

Parámetros de ruta

name string

Obligatorio. Es el nombre del File que se debe obtener. Ejemplo: files/abc-123 Toma la forma files/{file}.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Ejemplo de solicitud

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}`,
);

Cuerpo de la respuesta

Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene una instancia de File.

Método: files.list

Enumera los metadatos de las File que pertenecen al proyecto solicitante.

Extremo

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

Parámetros de consulta

pageSize integer

Opcional. Cantidad máxima de File que se mostrarán por página. Si no se especifica, el valor predeterminado es 10. El pageSize máximo es 100.

pageToken string

Opcional. Un token de página de una llamada files.list anterior.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Ejemplo de solicitud

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}`);
}

Cuerpo de la respuesta

La respuesta para files.list.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Campos
files[] object (File)

La lista de File.

nextPageToken string

Un token que se puede enviar como pageToken a una llamada files.list posterior.

Representación JSON
{
  "files": [
    {
      object (File)
    }
  ],
  "nextPageToken": string
}

Método: files.delete

Borra el File.

Extremo

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

Parámetros de ruta

name string

Obligatorio. El nombre de la File que se borrará. Ejemplo: files/abc-123 Toma la forma files/{file}.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Ejemplo de solicitud

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}`);

Cuerpo de la respuesta

Si se ejecuta correctamente, el cuerpo de la respuesta está vacío.

Recurso de REST: files

Recurso: Archivo

Un archivo subido a la API.

Representación 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

Inmutable. Identificador. Nombre del recurso de File. El ID (nombre sin el prefijo "files/") puede contener hasta 40 caracteres alfanuméricos en minúscula o guiones (-). El ID no puede comenzar ni terminar con un guion. Si el nombre está vacío durante la creación, se generará un nombre único. Ejemplo: files/123-456

displayName string

Opcional. Es el nombre visible del elemento File en lenguaje natural. El nombre visible no debe superar los 512 caracteres, incluidos los espacios. Ejemplo: "Imagen de bienvenida"

mimeType string

Solo salida. Es el tipo de MIME del archivo.

sizeBytes string (int64 format)

Solo salida. Tamaño del archivo expresado en bytes.

createTime string (Timestamp format)

Solo salida. La marca de tiempo de cuando se creó File.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".

updateTime string (Timestamp format)

Solo salida. La marca de tiempo de la última vez que se actualizó File.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".

expirationTime string (Timestamp format)

Solo salida. La marca de tiempo del momento en que se borrará File. Solo se establece si el File está programado para vencer.

Una marca de tiempo en formato RFC3339 UTC “Zulú”, con una resolución de nanosegundos y hasta nueve dígitos fraccionarios. Ejemplos: "2014-10-02T15:01:23Z" y "2014-10-02T15:01:23.045123456Z".

sha256Hash string (bytes format)

Solo salida. Hash SHA-256 de los bytes subidos.

String codificada en base64.

uri string

Solo salida. Es el URI del File.

state enum (State)

Solo salida. Estado de procesamiento del archivo.

error object (Status)

Solo salida. Estado de error si falló el procesamiento del archivo.

Campo de unión metadata. Metadatos del archivo Las direcciones (metadata) solo pueden ser una de las siguientes opciones:
videoMetadata object (VideoMetadata)

Solo salida. Metadatos de un video.

VideoMetadata

Metadatos de un video File.

Representación JSON
{
  "videoDuration": string
}
Campos
videoDuration string (Duration format)

Es la duración del video.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

Estado

Estados para el ciclo de vida de un archivo.

Enumeraciones
STATE_UNSPECIFIED Es el valor predeterminado. Este valor se usa si se omite el estado.
PROCESSING Se está procesando el archivo y aún no se puede usar para la inferencia.
ACTIVE El archivo se procesa y está disponible para inferencia.
FAILED No se pudo procesar el archivo.

Estado

El tipo de Status define un modelo de error lógico que es adecuado para entornos de programación diferentes, incluidas las API de REST y las API de RPC. Lo usa gRPC. Cada mensaje Status contiene tres datos: código de error, mensaje de error y detalles del error.

Puedes obtener más información sobre este modelo de error y cómo trabajar con él en la guía de diseño de API.

Representación JSON
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campos
code integer

El código de estado, que debe ser un valor enum de google.rpc.Code.

message string

Un mensaje de error dirigido al desarrollador, que debe estar en inglés. Cualquier mensaje de error dirigido al usuario debe localizarse y enviarse al campo google.rpc.Status.details; o el cliente debe localizarlo.

details[] object

Una lista de mensajes que contienen los detalles del error. Hay un conjunto común de tipos de mensajes para que usen las API.

Un objeto que contiene campos de un tipo arbitrario. Un campo adicional "@type" contiene una URI que identifica el tipo. Ejemplo: { "id": 1234, "@type": "types.example.com/standard/id" }.