# Gemini Quick Start

The UModelverse platform provides a **Models** interface compatible with the Google Gemini API. Developers can directly call the **Gemini model** on Modelverse using the Gemini SDK or other supported tools.

This article will guide you on how to quickly send your first Gemini API request on the UModelverse platform.

## Quick Start

### Install Google GenAI SDK
Install the SDK for Python language

> Use Python 3.9 or later versions, and install the google-genai package using the following pip command:

```python
pip install google-genai
```

### Example
The following example uses the generateContent method to send a request to the UModelverse API via the `gemini-2.5-flash` model.

> Make sure to replace `$MODELVERSE_API_KEY` with your own API Key. Obtain your [API Key](https://astraflow.ucloud.cn/modelverse/experience/api-keys).

#### Non-Streaming Call
You can make a call using the following code. Note that we need to specify the API address of Modelverse through `http_options`.

 <!-- tabs:start -->
#### ** python **

```python
from google import genai
from google.genai import types

client = genai.Client(
   api_key="<MODELVERSE_API_KEY>",
   http_options=types.HttpOptions(
       base_url="https://api-us-ca.umodelverse.ai"
   ),
)

response = client.models.generate_content(
   model="gemini-2.5-flash",
   contents=[
       {"text": "How does AI work?"},
   ],
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(thinking_budget=0),
   ),
)
print(response.text)
```
#### Parameter Description: Enable Thought Summary
For details, refer to the [official document](https://ai.google.dev/gemini-api/docs/thinking?hl=en#summaries)

To enable thought summary, add the following in `thinking_config`:

```python
config=types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(
        include_thoughts=True
    )
)
```
#### ** curl **

```bash
curl "https://api-us-ca.umodelverse.ai/v1beta/models/deepseek-ai/DeepSeek-V3.1:generateContent" \
    -H "x-goog-api-key: $MODELVERSE_API_KEY" \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{
          "contents": [
            {
              "parts": [
                {
                  "text": "How does AI work?"
                }
              ]
            }
          ],
          "generationConfig": {
            "thinkingConfig": {
              "thinkingBudget": 0
            }
          }
        }'
```
<!-- tabs:end -->


#### Streaming Call

 <!-- tabs:start -->
#### ** python **

```python
from google import genai
from google.genai import types

client = genai.Client(
    api_key="<MODELVERSE_API_KEY>",
    http_options=types.HttpOptions(
        base_url="https://api-us-ca.umodelverse.ai"
    ),
)

response = client.models.generate_content_stream(
    model="gemini-2.5-flash", contents=["Explain how AI works"]
)
for chunk in response:
    print(chunk.text, end="")

```

#### ** curl **

```bash
curl "https://api-us-ca.umodelverse.ai/v1beta/models/gemini-2.5-flash:GenerateContent?alt=sse" \
    -H "Authorization: Bearer $MODELVERSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            {
              "text": "Explain how AI works"
            }
          ]
        }
      ]
    }'
```
<!-- tabs:end -->

## Google Search (Web Retrieval) Usage Guide

Gemini supports real-time web retrieval via `tools.google_search`. When enabled, the model will automatically initiate searches when needed and return traceable source information (`groundingMetadata`) in the response.

> For detailed field definitions and capability descriptions, refer to the official Google Gemini documentation: https://ai.google.dev/gemini-api/docs/google-search

Applicable scenarios:

*   When up-to-date information is required (e.g., recent events, prices, announcements).
*   When verifiable sources and citation chains are needed.
*   When reducing hallucination risks caused by parametric knowledge.

### Request Key Points

*   Add `tools` in the request body and include `{"google_search": {}}`.
*   It is recommended to use Gemini models that support the Google Search tool (e.g., `gemini-3-flash-preview`).
*   Use Modelverse-compatible endpoint and authentication:
    *   Base URL: `https://api-us-ca.umodelverse.ai`
    *   API Key Header: `x-goog-api-key: $MODELVERSE_API_KEY`

### Example: Python SDK (Modelverse)

```python
from google import genai
from google.genai import types

client = genai.Client(
    api_key="<MODELVERSE_API_KEY>",
    http_options=types.HttpOptions(base_url="https://api-us-ca.umodelverse.ai"),
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Tell me the three most important AI news today and provide sources.",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    ),
)

print(response.text)


# Optional: Read grounding metadata (if search is triggered)
if response.candidates and response.candidates[0].grounding_metadata:
    gm = response.candidates[0].grounding_metadata
    if gm.grounding_chunks:
        for idx, chunk in enumerate(gm.grounding_chunks, 1):
            if chunk.web:
                print(f"[{idx}] {chunk.web.title}: {chunk.web.uri}")
```

### Example: curl (Modelverse)

```bash
curl "https://api-us-ca.umodelverse.ai/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Based on web information, summarize today’s global AI news and include sources."
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'
```

### Response Field Description (Key Points)

When a request triggers web retrieval, `candidates[*].groundingMetadata` commonly includes:

*   `webSearchQueries`: The actual search queries issued by the model.
*   `groundingChunks`: A list of candidate sources (including `uri`, `title`).
*   `groundingSupports`: A mapping between answer segments and source indices, which can be used for inline citations.

> It is recommended to display source links on the frontend to improve answer interpretability and user trust.

### Document Understanding

Gemini models can process PDF documents and use native vision capabilities to understand the full context of the document. This goes beyond simple text extraction and enables Gemini to:

*   Analyze and interpret content, including text, images, charts, diagrams, and tables—even for documents up to 1,000 pages.
*   Extract information in structured output formats.
*   Summarize content and answer questions based on both visual and textual elements in the document.
*   Transcribe document content (e.g., into HTML) while preserving layout and formatting for downstream applications.

You can also pass non-PDF documents in the same way, but Gemini will treat them as plain text, thereby losing contextual elements such as charts or formatting.

#### Passing PDF Data Inline
You can inline PDF data in requests sent to `generateContent`. This method is best suited for smaller documents or temporary processing, as there is no need to reference the file in subsequent requests.

The following example shows how to extract a PDF from a URL and convert it into bytes for processing:

 <!-- tabs:start -->
#### ** python **

```python
from google import genai
from google.genai import types
import httpx

client = genai.Client(
    api_key="<MODELVERSE_API_KEY>",
    http_options=types.HttpOptions(
        base_url="https://api-us-ca.umodelverse.ai"
    ),
)

doc_url = "https://umodelverse-inference.cn-wlcb.ufileos.com/gemini-pdf.pdf"

# Retrieve and encode the PDF byte
doc_data = httpx.get(doc_url).content

prompt = "Summarize this document"
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        types.Part.from_bytes(
            data=doc_data,
            mime_type='application/pdf',
        ),
        prompt
    ]
)

print(response.text)
```

#### ** curl **

```bash
DOC_URL="https://umodelverse-inference.cn-wlcb.ufileos.com/gemini-pdf.pdf"
PROMPT="Summarize this document"
DISPLAY_NAME="base64_pdf"

# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"

# Check for FreeBSD base64 and set flags accordingly
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

# Base64 encode the PDF
ENCODED_PDF=$(base64 $B64FLAGS "${DISPLAY_NAME}.pdf")

# Generate content using the base64 encoded PDF
curl "https://api-us-ca.umodelverse.ai/v1beta/models/gemini-3-flash-preview:generateContent" \
    -H "x-goog-api-key: $MODELVERSE_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"inline_data": {"mime_type": "application/pdf", "data": "'"$ENCODED_PDF"'"}},
          {"text": "'$PROMPT'"}
        ]
      }]
    }' 2> /dev/null > response.json

cat response.json
echo

jq ".candidates[].content.parts[].text" response.json

# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"
```
<!-- tabs:end -->

You can also read PDF files from local storage for processing:

```python
from google import genai
from google.genai import types
import pathlib

client = genai.Client(
    api_key="<MODELVERSE_API_KEY>",
    http_options=types.HttpOptions(
        base_url="https://api-us-ca.umodelverse.ai"
    ),
)

# Retrieve and encode the PDF byte
filepath = pathlib.Path('file.pdf')

prompt = "Summarize this document"
response = client.models.generate_content(
  model="gemini-3-flash-preview",
  contents=[
      types.Part.from_bytes(
        data=filepath.read_bytes(),
        mime_type='application/pdf',
      ),
      prompt])
print(response.text)
```

## Model ID Description
For more supported Gemini models, please refer to [Get Model List]

> For more field details, see the [Gemini official document](https://ai.google.dev/api/models?hl=en)