Skip to content

Improve key naming clarity and consistency across REST requests #683 #714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions samples/rest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,16 @@ These samples are embedded in parts of the [documentation](https://ai.google.dev

Each file is structured as a runnable script, ensuring that samples are executable and functional. Each filee contains region tags that are used to demarcate the script from the spotlight code. If you are contributing, code within region tags should follow sample code best practices - being clear, complete and concise.

## Parameter Naming Conventions

The Gemini API accepts REST parameters in camelCase format, which is the convention used in these examples and the official API reference. For example:
- `generationConfig`
- `maxOutputTokens`
- `systemInstruction`
- `topP`, `topK`

**Note:** While the API also accepts snake_case format for compatibility (e.g., `system_instruction` instead of `systemInstruction`), the official and recommended style is camelCase for REST API requests.

## Contents

| File | Description |
Expand All @@ -19,6 +29,7 @@ Each file is structured as a runnable script, ensuring that samples are executab
| [embed.sh](./embed.sh) | Generating embeddings |
| [files.sh](./files.sh) | Managing files with the File API |
| [function_calling.sh](./function_calling.sh) | Using function calling |
| [inline_pdf_example.sh](./inline_pdf_example.sh) | Using inline PDF data with the API |
| [models.sh](./models.sh) | Listing models and model metadata |
| [safety_settings.sh](./safety_settings.sh) | Setting and using safety controls |
| [system_instruction.sh](./system_instruction.sh) | Setting system instructions |
Expand Down
4 changes: 2 additions & 2 deletions samples/rest/cache.sh
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ echo '{
{
"parts":[
{
"inline_data": {
"mime_type":"text/plain",
"inlineData": {
"mimeType":"text/plain",
"data": "'$(base64 $B64FLAGS a11.txt)'"
}
}
Expand Down
4 changes: 2 additions & 2 deletions samples/rest/chat.sh
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ curl https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:st
"text": "Tell me about this instrument"
},
{
"inline_data": {
"mime_type": "image/jpeg",
"inlineData": {
"mimeType": "image/jpeg",
"data": "'$(base64 $B64FLAGS $IMG_PATH)'"
}
}
Expand Down
6 changes: 3 additions & 3 deletions samples/rest/controlled_generation.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
]
}],
"generationConfig": {
"response_mime_type": "application/json",
"response_schema": {
"responseMimeType": "application/json",
"responseSchema": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
Expand All @@ -39,6 +39,6 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
}
]
}],
"generationConfig": { "response_mime_type": "application/json" }
"generationConfig": { "responseMimeType": "application/json" }
}' 2> /dev/null | head
# [END json_no_schema]
24 changes: 12 additions & 12 deletions samples/rest/count_tokens.sh
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to apply the consistency changes to the following files:

  • samples/rest/count_tokens.sh lines:116-118, line:174, lines:274-275

Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,8 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:c
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"inlineData": {
"mimeType":"image/jpeg",
"data": "'$(base64 $B64FLAGS $IMG_PATH)'"
}
}
Expand Down Expand Up @@ -113,9 +113,9 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:c
"contents": [{
"parts":[
{"text": "Can you tell me about the instruments in this photo?"},
{"file_data":
{"mime_type": "image/jpeg",
"file_uri": '$file_uri'}
{"fileData":
{"mimeType": "image/jpeg",
"fileUri": '$file_uri'}
}]
}]
}'
Expand Down Expand Up @@ -171,7 +171,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:c
"contents": [{
"parts":[
{"text": "Describe this video clip"},
{"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "video/mp4", "fileUri": '$file_uri'}}]
}]
}'
# [END tokens_multimodal_video_audio_file_api]
Expand All @@ -184,8 +184,8 @@ echo '{
{
"parts":[
{
"inline_data": {
"mime_type":"text/plain",
"inlineData": {
"mimeType":"text/plain",
"data": "'$(base64 $B64FLAGS $A11_PATH)'"
}
}
Expand Down Expand Up @@ -215,7 +215,7 @@ echo "[START tokens_system_instruction]"
# [START tokens_system_instruction]
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-latest:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
-d '{ "systemInstruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
Expand Down Expand Up @@ -264,15 +264,15 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-pro-lat
-H 'Content-Type: application/json' \
-d '
{
"system_instruction": {
"systemInstruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(source "$tools")'],

"tool_config": {
"function_calling_config": {"mode": "none"}
"toolConfig": {
"functionCallingConfig": {"mode": "none"}
},

"contents": {
Expand Down
6 changes: 3 additions & 3 deletions samples/rest/function_calling.sh
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to apply the consistency changes to the following files:

  • samples/rest/function_calling.sh lines:48-49

Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,15 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
-H 'Content-Type: application/json' \
-d @<(echo '
{
"system_instruction": {
"systemInstruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(cat tools.json)'],

"tool_config": {
"function_calling_config": {"mode": "auto"}
"toolConfig": {
"functionCallingConfig": {"mode": "auto"}
},

"contents": {
Expand Down
88 changes: 88 additions & 0 deletions samples/rest/inline_pdf_example.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
#!/bin/bash
# -*- coding: utf-8 -*-
# Copyright 2023 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# This example demonstrates how to use inline PDF data with the generative API

# Set default values for environment variables if they don't exist
MEDIA_DIR="${MEDIA_DIR:-$(dirname "$0")/../../third_party}"

# Check if we're on macOS or Linux
if [[ "$OSTYPE" == "darwin"* ]]; then
B64FLAGS="-b 0"
else
B64FLAGS="--wrap=0"
fi

echo "[START text_gen_multimodal_two_pdf_inline]"
# Use temporary files to hold the base64 encoded pdf data
PDF_PATH_1=${MEDIA_DIR}/test.pdf
PDF_PATH_2=${MEDIA_DIR}/test.pdf

TEMP_1_B64=$(mktemp)
trap 'rm -f "$TEMP_1_B64"' EXIT
base64 $B64FLAGS $PDF_PATH_1 > "$TEMP_1_B64"

TEMP_2_B64=$(mktemp)
trap 'rm -f "$TEMP_2_B64"' EXIT
base64 $B64FLAGS $PDF_PATH_2 > "$TEMP_2_B64"

# Use a temporary file to hold the JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT

cat > "$TEMP_JSON" << EOF
{
"contents": [{
"role": "user",
"parts":[
{"text": "Extract the pet names, type and ages from these documents."},
{
"inlineData": {
"mimeType":"application/pdf",
"data": "$(cat "$TEMP_1_B64")"
}
},
{
"inlineData": {
"mimeType":"application/pdf",
"data": "$(cat "$TEMP_2_B64")"
}
}
]
}],
"systemInstruction": {
"parts": [
{"text": "Extract the pet names and ages from these documents and return them in the following JSON format:

Pet = {\"name\": str, \"type\": str, \"age\": int}
Return: list[Pet]"
}
]
},
"generationConfig": {
"temperature": 0.2,
"topP": 0.95,
"topK": 40,
"maxOutputTokens": 1000,
"responseMimeType": "application/json"
}
}
EOF

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
2 changes: 1 addition & 1 deletion samples/rest/system_instruction.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ echo "[START system_instruction]"
# [START system_instruction]
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
-d '{ "systemInstruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
Expand Down
32 changes: 16 additions & 16 deletions samples/rest/text_generation.sh
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need to apply the consistency changes to the following places:

  • samples/rest/text_generation.sh line:213, line:263, line:324, line:384, line:434, line:486

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will fix this immediately

Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ cat > "$TEMP_JSON" << EOF
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"inlineData": {
"mimeType":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
Expand All @@ -78,8 +78,8 @@ cat > "$TEMP_JSON" << EOF
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"inlineData": {
"mimeType":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
Expand Down Expand Up @@ -109,14 +109,14 @@ cat > "$TEMP_JSON" << EOF
"contents": [{
"parts":[
{
"inline_data": {
"mime_type": "image/jpeg",
"inlineData": {
"mimeType": "image/jpeg",
"data": "$(cat "$TEMP_B64_1")"
}
},
{
"inline_data": {
"mime_type": "image/jpeg",
"inlineData": {
"mimeType": "image/jpeg",
"data": "$(cat "$TEMP_B64_2")"
}
},
Expand Down Expand Up @@ -148,8 +148,8 @@ cat > "$TEMP_JSON" << EOF
"contents": [{
"parts":[
{
"inline_data": {
"mime_type": "image/jpeg",
"inlineData": {
"mimeType": "image/jpeg",
"data": "$(cat "$TEMP_B64_2")"
}
},
Expand Down Expand Up @@ -210,7 +210,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
"contents": [{
"parts":[
{"text": "Please describe this file."},
{"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "audio/mpeg", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down Expand Up @@ -260,7 +260,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:s
"contents": [{
"parts":[
{"text": "Please describe this file."},
{"file_data":{"mime_type": "audio/mpeg", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "audio/mpeg", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down Expand Up @@ -321,7 +321,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
"contents": [{
"parts":[
{"text": "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."},
{"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "video/mp4", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down Expand Up @@ -381,7 +381,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:s
"contents": [{
"parts":[
{"text": "Please describe this file."},
{"file_data":{"mime_type": "video/mp4", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "video/mp4", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down Expand Up @@ -431,7 +431,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:g
"contents": [{
"parts":[
{"text": "Can you add a few more lines to this poem?"},
{"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "application/pdf", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down Expand Up @@ -483,7 +483,7 @@ curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:s
"contents": [{
"parts":[
{"text": "Can you add a few more lines to this poem?"},
{"file_data":{"mime_type": "application/pdf", "file_uri": '$file_uri'}}]
{"fileData":{"mimeType": "application/pdf", "fileUri": '$file_uri'}}]
}]
}' 2> /dev/null > response.json

Expand Down