跳转到主要内容

​
推荐 endpoint

​
最小请求

{
  "model": "gemini-2.5-flash",
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "查询今天上海天气。" }]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "查询天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string" }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

​
cURL 示例

FIRST_RESPONSE=$(curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "查询今天上海天气。" }]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_weather",
            "description": "查询天气",
            "parameters": {
              "type": "object",
              "properties": {
                "city": { "type": "string" }
              },
              "required": ["city"]
            }
          }
        ]
      }
    ]
  }')

FUNCTION_CALL=$(echo "$FIRST_RESPONSE" | jq -c '.candidates[0].content.parts[] | select(.functionCall) | .functionCall')

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [
      {
        \"role\": \"user\",
        \"parts\": [{ \"text\": \"查询今天上海天气。\" }]
      },
      {
        \"role\": \"model\",
        \"parts\": [{ \"functionCall\": $FUNCTION_CALL }]
      },
      {
        \"role\": \"user\",
        \"parts\": [
          {
            \"functionResponse\": {
              \"name\": \"get_weather\",
              \"response\": {
                \"result\": {
                  \"city\": \"上海\",
                  \"condition\": \"多云\",
                  \"temperature\": 24
                }
              }
            }
          }
        ]
      }
    ],
    \"tools\": [
      {
        \"functionDeclarations\": [
          {
            \"name\": \"get_weather\",
            \"description\": \"查询天气\",
            \"parameters\": {
              \"type\": \"object\",
              \"properties\": {
                \"city\": { \"type\": \"string\" }
              },
              \"required\": [\"city\"]
            }
          }
        ]
      }
    ]
  }"

​
Python 示例

import requests

url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent"
headers = {
    "x-goog-api-key": "<GEMINI_API_KEY>",
    "Content-Type": "application/json",
}
tools = [
    {
        "functionDeclarations": [
            {
                "name": "get_weather",
                "description": "查询天气",
                "parameters": {
                    "type": "object",
                    "properties": {"city": {"type": "string"}},
                    "required": ["city"],
                },
            }
        ]
    }
]

first_response = requests.post(
    url,
    headers=headers,
    json={
        "contents": [
            {
                "role": "user",
                "parts": [{"text": "查询今天上海天气。"}],
            }
        ],
        "tools": tools,
    },
    timeout=60,
)
first_response.raise_for_status()

function_call = next(
    part["functionCall"]
    for part in first_response.json()["candidates"][0]["content"]["parts"]
    if "functionCall" in part
)

final_response = requests.post(
    url,
    headers=headers,
    json={
        "contents": [
            {
                "role": "user",
                "parts": [{"text": "查询今天上海天气。"}],
            },
            {
                "role": "model",
                "parts": [{"functionCall": function_call}],
            },
            {
                "role": "user",
                "parts": [
                    {
                        "functionResponse": {
                            "name": "get_weather",
                            "response": {
                                "result": {
                                    "city": "上海",
                                    "condition": "多云",
                                    "temperature": 24,
                                }
                            },
                        }
                    }
                ],
            },
        ],
        "tools": tools,
    },
    timeout=60,
)
final_response.raise_for_status()

print(final_response.json()["candidates"][0]["content"]["parts"][0]["text"])

​
Node.js 示例

const url =
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent";

const tools = [
  {
    functionDeclarations: [
      {
        name: "get_weather",
        description: "查询天气",
        parameters: {
          type: "object",
          properties: {
            city: { type: "string" }
          },
          required: ["city"]
        }
      }
    ]
  }
];

const firstResponse = await fetch(url, {
  method: "POST",
  headers: {
    "x-goog-api-key": process.env.GEMINI_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    contents: [
      {
        role: "user",
        parts: [{ text: "查询今天上海天气。" }]
      }
    ],
    tools
  })
});

const firstData = await firstResponse.json();
const functionCall = firstData.candidates[0].content.parts.find(
  (part) => part.functionCall
).functionCall;

const finalResponse = await fetch(url, {
  method: "POST",
  headers: {
    "x-goog-api-key": process.env.GEMINI_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    contents: [
      {
        role: "user",
        parts: [{ text: "查询今天上海天气。" }]
      },
      {
        role: "model",
        parts: [{ functionCall }]
      },
      {
        role: "user",
        parts: [
          {
            functionResponse: {
              name: "get_weather",
              response: {
                result: {
                  city: "上海",
                  condition: "多云",
                  temperature: 24
                }
              }
            }
          }
        ]
      }
    ],
    tools
  })
});

const finalData = await finalResponse.json();
console.log(finalData.candidates[0].content.parts[0].text);

​
最佳实践

  • Gemini 的函数声明和 OpenAI / Claude 写法不同，单独做映射层
  • 允许模型并行或连续调用多个函数时，执行层要支持批量处理
  • 函数说明比函数名更重要，描述越清晰，参数越稳定