Using files

메서드: media.upload

File를 만듭니다.

엔드포인트

<ph type="x-smartling-placeholder"></ph> 미디어 업로드 요청의 경우 업로드 URI:
`post
https://generativelanguage.googleapis.com/upload/v1beta/files

  • 메타데이터 전용 요청의 메타데이터 URI:
    POST https://generativelanguage.googleapis.com/v1beta/filesURL은 gRPC 트랜스코딩 구문을 사용합니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

<ph type="x-smartling-placeholder">
</ph> 입력란
file object (File)

선택사항. 생성할 파일의 메타데이터입니다.

요청 예시

이미지

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

오디오

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

텍스트

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

동영상

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

응답 본문

media.upload에 대한 응답입니다.

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

입력란
file object (File)

생성된 파일의 메타데이터입니다.

JSON 표현
{
  "file": {
    object (File)
  }
}

메서드: files.get

지정된 File의 메타데이터를 가져옵니다.

엔드포인트

<ph type="x-smartling-placeholder"></ph> 받기 https://generativelanguage.googleapis.com/v1beta/{name=files/*}

경로 매개변수

name string

필수 항목입니다. 가져올 File의 이름입니다. 예: files/abc-123 files/{file} 형식을 취합니다.

요청 본문

요청 본문은 비어 있어야 합니다.

요청 예시

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

응답 본문

성공한 경우 응답 본문에 File의 인스턴스가 포함됩니다.

메서드: files.list

요청하는 프로젝트가 소유한 File의 메타데이터를 나열합니다.

엔드포인트

<ph type="x-smartling-placeholder"></ph> 받기 https://generativelanguage.googleapis.com/v1beta/files

쿼리 매개변수

pageSize integer

선택사항. 페이지당 반환할 최대 File 수입니다. 지정하지 않으면 기본값은 10입니다. 최댓값은 pageSize 100입니다.

pageToken string

선택사항. 이전 files.list 호출의 페이지 토큰입니다.

요청 본문

요청 본문은 비어 있어야 합니다.

요청 예시

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

응답 본문

files.list에 대한 응답입니다.

성공할 경우 응답 본문에 다음 구조의 데이터가 포함됩니다.

입력란
files[] object (File)

File의 목록입니다.

nextPageToken string

후속 files.list 호출에 pageToken로 전송할 수 있는 토큰입니다.

JSON 표현
{
  "files": [
    {
      object (File)
    }
  ],
  "nextPageToken": string
}

메서드: files.delete

File를 삭제합니다.

엔드포인트

<ph type="x-smartling-placeholder"></ph> 삭제 https://generativelanguage.googleapis.com/v1beta/{name=files/*}

경로 매개변수

name string

필수 항목입니다. 삭제할 File의 이름입니다. 예: files/abc-123 files/{file} 형식을 취합니다.

요청 본문

요청 본문은 비어 있어야 합니다.

요청 예시

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

응답 본문

성공한 경우 응답 본문은 비어 있습니다.

REST 리소스: 파일

리소스: 파일

API에 업로드된 파일입니다.

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.
}
입력란
name string

변경할 수 없습니다. 식별자. File 리소스 이름입니다. ID('files/' 접두사를 제외한 이름)에는 소문자 영숫자 또는 대시(-)로 구성된 최대 40자(영문 기준)를 포함할 수 있습니다. ID는 대시로 시작하거나 끝날 수 없습니다. 생성 시 이름이 비어 있으면 고유한 이름이 생성됩니다. 예: files/123-456

displayName string

선택사항. 사람이 읽을 수 있는 File의 표시 이름입니다. 표시 이름은 공백을 포함하여 512자(영문 기준) 이하여야 합니다. 예: '환영 이미지'

mimeType string

출력 전용입니다. 파일의 MIME 유형입니다.

sizeBytes string (int64 format)

출력 전용입니다. 바이트 단위의 파일 크기입니다.

createTime string (Timestamp format)

출력 전용입니다. File가 생성된 시점의 타임스탬프입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

updateTime string (Timestamp format)

출력 전용입니다. File가 마지막으로 업데이트된 시점의 타임스탬프입니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

expirationTime string (Timestamp format)

출력 전용입니다. File 삭제 시점의 타임스탬프입니다. File가 만료될 예정인 경우에만 설정됩니다.

RFC3339 UTC 'Zulu' 형식의 타임스탬프입니다(나노초 단위, 소수점 이하 9자리). 예를 들면 "2014-10-02T15:01:23Z""2014-10-02T15:01:23.045123456Z"입니다.

sha256Hash string (bytes format)

출력 전용입니다. 업로드된 바이트의 SHA-256 해시입니다.

base64 인코딩 문자열입니다.

uri string

출력 전용입니다. File의 URI입니다.

state enum (State)

출력 전용입니다. 파일의 처리 상태입니다.

error object (Status)

출력 전용입니다. 파일 처리에 실패한 경우 오류 상태입니다.

통합 필드 metadata. 파일의 메타데이터입니다. metadata은 다음 중 하나여야 합니다.
videoMetadata object (VideoMetadata)

출력 전용입니다. 동영상의 메타데이터입니다.

VideoMetadata

File 동영상의 메타데이터입니다.

JSON 표현
{
  "videoDuration": string
}
입력란
videoDuration string (Duration format)

동영상의 길이입니다.

소수점 아래가 최대 9자리까지이고 's'로 끝나는 초 단위 기간입니다. 예를 들면 "3.5s"입니다.

파일의 수명 주기 상태입니다.

열거형
STATE_UNSPECIFIED 기본값입니다. 상태가 생략된 경우 이 값이 사용됩니다.
PROCESSING 파일을 처리 중이며 아직 추론에 사용할 수 없습니다.
ACTIVE 파일이 처리되고 추론에 사용할 수 있습니다.
FAILED 파일을 처리하지 못했습니다.

상태

Status 유형은 REST API, RPC API를 비롯하여 다양한 프로그래밍 환경에 적합한 논리적 오류 모델을 정의하며, gRPC에서 사용됩니다. 각 Status 메시지에는 오류 코드, 오류 메시지, 오류 세부정보라는 3가지 데이터가 포함됩니다.

API 설계 가이드에서 이 오류 모델과 모델 작업 방법에 대해 자세히 알아볼 수 있습니다.

JSON 표현
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
입력란
code integer

상태 코드로, google.rpc.Code의 열거형 값이어야 합니다.

message string

개발자에게 정보를 제공하는 오류 메시지로, 영어로 작성되어야 합니다. 사용자에게 표시되는 모든 오류 메시지는 현지화되어 google.rpc.Status.details 필드에 전송되거나, 클라이언트 측에서 현지화되어야 합니다.

details[] object

오류 세부정보를 설명하는 메시지 목록입니다. API에서 사용할 일반적인 메시지 유형 집합이 있습니다.

임의 유형의 필드를 포함하는 객체입니다. 추가 필드 "@type"은 유형을 식별하는 URI를 포함합니다. 예: { "id": 1234, "@type": "types.example.com/standard/id" }