Gemini protocol: generateContent and SDK

Use Gemini’s native generateContent endpoint when your application already sends Gemini-style requests. Point the Google Gen AI SDK or your requests at https://api.laozhang.ai and use your LaoZhang API key.

Item	Details
Request and response	Send `contents` to `generateContent` and read `candidates`
Format	Gemini Developer API format, `v1beta` version, model ID in the path
Models	Those that list Gemini under Endpoints in the model catalog
Example model	`gemini-3.8-flash`
Media input	Images, PDFs, audio, and MP4 video; for video, see the Video understanding API

The endpoint is:

POST https://api.laozhang.ai/v1beta/models/{model}:generateContent

If your application already uses OpenAI-style messages, call Gemini models with the OpenAI protocol instead.

Credentials and model selection

Create a model API key in Token management with its billing mode set to Usage first (按量优先, recommended) or Usage-based (按量计费), and export it in your terminal:

export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"

Models that list Gemini under Endpoints in the model catalog accept this format. These examples use gemini-3.8-flash; confirm that your token group can use it in Models and pricing. Native Gemini requests accept either Authorization: Bearer or x-goog-api-key authentication. The Google Gen AI SDK supplies the API key header automatically.

Generate text

cURL
Python

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Reply only with: connected"}]
    }]
  }'

To use Google’s API key header instead, replace the Authorization header with:

-H "x-goog-api-key: $LAOZHANG_API_KEY"

Install the SDK:

python -m pip install google-genai

Set base_url to the host root and api_version to v1beta. The SDK adds the version and model path; its timeout is expressed in milliseconds.

import os
from google import genai

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Reply only with: connected",
)
print(response.text)

The reply should contain connected. Do not append /v1 to the Google SDK base URL or use a Vertex AI project/location/publisher path for this endpoint.

Stream the reply

To stream the reply, send the same body to https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse; each server-sent event carries a partial response with the same candidates structure.

Request structure

contents holds the messages in order. Each message has a role and one or more parts.

Field	Meaning
`contents`	Required array of conversation messages.
`role`	`user` for user input; `model` for a model reply.
`parts`	Message content, including text and any media the model accepts.
`text`	A text part.
`inlineData`	Inline media with a `mimeType` and Base64-encoded `data`.
`fileData`	Media referenced by URL, with a `fileUri` and `mimeType`.
`systemInstruction`	Instructions supplied separately from the conversation.
`generationConfig`	Model-specific settings for generation.

REST JSON uses camelCase, such as inlineData and mimeType. Python SDK properties use names such as inline_data and mime_type; use the spelling appropriate to the interface you are calling. Optional settings and media support depend on the model.

Include an image

For a model that accepts image input, such as gemini-3.8-flash, put a text part and an inlineData part in the same message. The following code reads a local input.png and writes the JSON request.

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "Describe the objects in this image."},
            {"inlineData": {
                "mimeType": "image/png",
                "data": base64.b64encode(Path("input.png").read_bytes()).decode("ascii"),
            }},
        ],
    }],
}
Path("gemini-request.json").write_text(json.dumps(request), encoding="utf-8")

Send that file as the request body:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-request.json

The MIME type must match the actual image. data contains raw Base64 without a data:image/png;base64, prefix. Describing an image and generating one are different operations. To create or edit images with Gemini image models, see the Nano Banana API overview. To send images to a vision model in the OpenAI format, see the Image understanding API.

Send a PDF or audio file

PDFs and audio go in inlineData just like images; only mimeType changes:

File	`mimeType`	What the model can do
PDF	`application/pdf`	Read every page and answer questions that span pages
MP3 audio	`audio/mp3`	Transcribe English or Chinese speech, summarize it, or answer questions about it

This example reads invoice.pdf from the current directory. For audio, change the file name to audio.mp3, set mimeType to audio/mp3, and adjust the prompt.

cURL
Python SDK

Write the request body:

import base64
import json
from pathlib import Path

request = {
    "contents": [{
        "role": "user",
        "parts": [
            {"inlineData": {
                "mimeType": "application/pdf",
                "data": base64.b64encode(Path("invoice.pdf").read_bytes()).decode("ascii"),
            }},
            {"text": "What are the invoice number, total due, and due date?"},
        ],
    }],
}
Path("gemini-file-request.json").write_text(json.dumps(request), encoding="utf-8")

Then send it:

curl --fail-with-body --max-time 120 \
  "https://api.laozhang.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @gemini-file-request.json

import os
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["LAOZHANG_API_KEY"],
    http_options={
        "base_url": "https://api.laozhang.ai",
        "api_version": "v1beta",
        "timeout": 120_000,
    },
)
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_bytes(
            data=Path("audio.mp3").read_bytes(),
            mime_type="audio/mp3",
        ),
        "Transcribe this audio, then summarize it in one sentence.",
    ],
)
print(response.text)

Audio is billed by token and appears as AUDIO in usageMetadata.promptTokensDetails. If you only need a transcript and no further reasoning, the audio transcription API also works.

Understand a video

MP4 video also goes in inlineData, with mimeType set to video/mp4. For a public URL or a public YouTube video, pass it with fileData instead. The model reads the frames and the audio track together:

{"inlineData": {"mimeType": "video/mp4", "data": "<BASE64_DATA>"}}

{"fileData": {"fileUri": "https://www.youtube.com/watch?v=9hE5-98ZeCg", "mimeType": "video/mp4"}}

Full examples and common tasks are on the Video understanding API page:

Send a local video or analyze a video URL.
Split a video into timestamped chapters or return structured JSON.
Clip a segment or change the frame rate with videoMetadata.
Compare videos, stream the answer, or call it with the OpenAI SDK.

Read the response

A text reply has this shape, with other metadata omitted:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "connected"}]
    },
    "finishReason": "STOP"
  }]
}

Read text from the candidate’s content.parts, which may contain more than one part. The Python SDK’s response.text helper collects text for you. Keep the full candidate content when your application needs media, tool calls, or conversation history. If a response has no text, inspect promptFeedback, finishReason, and any non-text parts. Content blocking, an output limit, or a tool call needs different handling from a network error. Usage details, when present, appear in usageMetadata; account charges are available in call logs.

Continue a conversation

Send the earlier user message, the complete model reply, and the new user message in contents. Gemini uses model for model replies, not assistant. Preserve returned parts when continuing a model workflow. For models that return thoughtSignature, pass the signature back unchanged with its part. For tool-calling models, pair each functionCall with the appropriate functionResponse; a plain text summary is not a substitute for the tool result structure. See Google’s generateContent reference for these message formats.

Troubleshooting

401: check the API key and authentication header. Use a model API key, not an account management AccessToken.
404 or model not found: check v1beta, the exact model ID, and the token group’s native Gemini access.
400: inspect contents, parts, message roles, media encoding, and optional configuration named in the error.
A response without text: inspect candidates, finish reasons, blocking feedback, and non-text content.
400 with “Cannot fetch content from the provided URL”: the video URL cannot be downloaded directly. Use a public direct link, or send the file with inlineData.
A file upload returns a web page or 404: the File API is not available. Use inlineData or a fileData URL instead.
cURL works but the SDK fails: check the SDK’s base URL and API version. The final URL should contain /v1beta/models/ only once.

For a timeout or temporary server error, check call logs before retrying. Keep the request time, model, and redacted error when contacting support.

FAQ

How much does the Gemini API cost, and do I need a Google account?

No Google account or AI Studio API key is needed; a LaoZhang API key is enough, and Gemini text models are billed by tokens from a prepaid balance. Public pricing as of October 14, 2026, per 1M tokens:

gemini-4-argon: $2 input, $10 output
gemini-3.8-flash: $0.75 input, $3.75 output
gemini-2.5-flash: $0.3 input, $2.4 output

Other Gemini models and long-context tiers are in the model and pricing catalog, and each request’s charge is in call logs. There is no platform limit on concurrency and no throttling; a 429 comes from upstream capacity, see Concurrency and 429.

Which media can I send through the OpenAI-compatible endpoint?

With Gemini models on /v1/chat/completions:

Images: send a URL or Base64 data URL in image_url; see the Image understanding API.
Video: send a Base64 data URL in video_url; see Call it with the OpenAI SDK.
PDFs in file parts and audio in input_audio parts are dropped. The request still returns 200, and the model may answer without having seen the file. Send them with inlineData on this page instead.

Can Gemini models use the Responses API?

No. Gemini models return a 400 on /v1/responses. With the OpenAI SDK, call Chat Completions; for PDFs, audio, video, or video URLs, use the native endpoint on this page.

Is the Google File API supported?

No. None of these are available:

The /upload/v1beta/files upload endpoint
files/... references
The SDK’s client.files.upload()

Send local files with inlineData and public videos with a fileData URL.

How is media input billed?

Gemini text models bill by token. Images, PDFs, audio, and video are all converted to input tokens, and usageMetadata.promptTokensDetails lists them by type, such as IMAGE, AUDIO, and VIDEO. Prices are in the model catalog, and the charge for each request is in call logs.

Can I call Veo or Nano Banana Pro natively?

Nano Banana Pro: gemini-3-pro-image works with native generateContent; see Nano Banana Pro image generation.
Veo: as of September 28, 2026, Veo is not in the public model catalog, and native predictLongRunning requests return a no-available-channel error. For video generation, use Wan 2.7 or Seedance 2.0.

Do Google models run on AI Studio or Vertex AI?

AI Studio. LaoZhang API calls Gemini text models and Nano Banana image models through Google’s Gemini API (AI Studio), not Vertex AI. As a result:

Model IDs, shutdown dates, and safety policies follow the Gemini API documentation, such as Google’s deprecations page.
Requests use the AI Studio-style v1beta path, with no Vertex project or location.
If you suspect an upstream outage, check the AI Studio status page for Gemini API incidents.

Get started

Image Generation & Editing APIs

Video Generation APIs

Text APIs

Multimodal & Audio APIs

Gemini protocol: generateContent and SDK

Credentials and model selection

Generate text

Stream the reply

Request structure

Include an image

Send a PDF or audio file

Understand a video

Read the response

Continue a conversation

Troubleshooting

FAQ

How much does the Gemini API cost, and do I need a Google account?

Which media can I send through the OpenAI-compatible endpoint?

Can Gemini models use the Responses API?

Is the Google File API supported?

How is media input billed?

Can I call Veo or Nano Banana Pro natively?

Do Google models run on AI Studio or Vertex AI?

​Credentials and model selection

​Generate text

​Stream the reply

​Request structure

​Include an image

​Send a PDF or audio file

​Understand a video

​Read the response

​Continue a conversation

​Troubleshooting

​FAQ

​How much does the Gemini API cost, and do I need a Google account?

​Which media can I send through the OpenAI-compatible endpoint?

​Can Gemini models use the Responses API?

​Is the Google File API supported?

​How is media input billed?

​Can I call Veo or Nano Banana Pro natively?

​Do Google models run on AI Studio or Vertex AI?

​Related documentation

Credentials and model selection

Generate text

Stream the reply

Request structure

Include an image

Send a PDF or audio file

Understand a video

Read the response

Continue a conversation

Troubleshooting

FAQ

How much does the Gemini API cost, and do I need a Google account?

Which media can I send through the OpenAI-compatible endpoint?

Can Gemini models use the Responses API?

Is the Google File API supported?

How is media input billed?

Can I call Veo or Nano Banana Pro natively?

Do Google models run on AI Studio or Vertex AI?

Related documentation