The Gemini API supports uploading media files separately from the prompt input, allowing your media to be reused across multiple requests and multiple prompts. For more details, check out the Prompting with media guide.
Method: media.upload
Creates a File
.
Endpoint
- Upload URI, for media upload requests:
https://generativelanguage.googleapis.com/upload/v1beta/files
- Metadata URI, for metadata-only requests:
https://generativelanguage.googleapis.com/v1beta/files
Request body
The request body contains data with the following structure:
Optional. Metadata for the file to create.
Example request
Image
Python
Node.js
Go
Shell
Audio
Python
Node.js
Go
Shell
Text
Python
Node.js
Go
Shell
Video
Python
Node.js
Go
Shell
Python
Method: files.get
Gets the metadata for the given File
.
Endpoint
get
https://generativelanguage.googleapis.com/v1beta/{name=files/*}
Path parameters
name
string
Required. The name of the File
to get. Example: files/abc-123
It takes the form files/{file}
.
Request body
The request body must be empty.
Example request
Python
Node.js
Go
Shell
Response body
If successful, the response body contains an instance of File
.
Method: files.list
Lists the metadata for File
s owned by the requesting project.
Endpoint
get
https://generativelanguage.googleapis.com/v1beta/files
Query parameters
pageSize
integer
Optional. Maximum number of File
s to return per page. If unspecified, defaults to 10. Maximum pageSize
is 100.
pageToken
string
Optional. A page token from a previous files.list
call.
Request body
The request body must be empty.
Example request
Python
Node.js
Go
Shell
Response body
Response for files.list
.
If successful, the response body contains data with the following structure:
The list of File
s.
nextPageToken
string
A token that can be sent as a pageToken
into a subsequent files.list
call.
JSON representation |
---|
{
"files": [
{
object ( |
Method: files.delete
Deletes the File
.
Endpoint
delete
https://generativelanguage.googleapis.com/v1beta/{name=files/*}
Path parameters
name
string
Required. The name of the File
to delete. Example: files/abc-123
It takes the form files/{file}
.
Request body
The request body must be empty.
Example request
Python
Node.js
Go
Shell
Response body
If successful, the response body is empty.
REST Resource: files
Resource: File
A file uploaded to the API.
name
string
Immutable. Identifier. The File
resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: files/123-456
displayName
string
Optional. The human-readable display name for the File
. The display name must be no more than 512 characters in length, including spaces. Example: "Welcome Image"
mimeType
string
Output only. MIME type of the file.
Output only. Size of the file in bytes.
Output only. The timestamp of when the File
was created.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
Output only. The timestamp of when the File
was last updated.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
Output only. The timestamp of when the File
will be deleted. Only set if the File
is scheduled to expire.
A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z"
and "2014-10-02T15:01:23.045123456Z"
.
Output only. SHA-256 hash of the uploaded bytes.
A base64-encoded string.
uri
string
Output only. The uri of the File
.
Output only. Processing state of the File.
Output only. Error status if File processing failed.
metadata
. Metadata for the File. metadata
can be only one of the following:Output only. Metadata for a video.
JSON representation |
---|
{ "name": string, "displayName": string, "mimeType": string, "sizeBytes": string, "createTime": string, "updateTime": string, "expirationTime": string, "sha256Hash": string, "uri": string, "state": enum ( |
VideoMetadata
Metadata for a video File
.
Duration of the video.
A duration in seconds with up to nine fractional digits, ending with 's
'. Example: "3.5s"
.
JSON representation |
---|
{ "videoDuration": string } |
State
States for the lifecycle of a File.
Enums | |
---|---|
STATE_UNSPECIFIED |
The default value. This value is used if the state is omitted. |
PROCESSING |
File is being processed and cannot be used for inference yet. |
ACTIVE |
File is processed and available for inference. |
FAILED |
File failed processing. |
Status
The Status
type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status
message contains three pieces of data: error code, error message, and error details.
You can find out more about this error model and how to work with it in the API Design Guide.
code
integer
The status code, which should be an enum value of google.rpc.Code
.
message
string
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details
field, or localized by the client.
details[]
object
A list of messages that carry the error details. There is a common set of message types for APIs to use.
An object containing fields of an arbitrary type. An additional field "@type"
contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }
.
JSON representation |
---|
{ "code": integer, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |