Skip to Content
Launching the open-source gateway

Google GenerateContent

Call models with the Google GenAI SDK, or call Gemini models with the OpenAI format.

The gateway serves Gemini’s generateContent API. Point the Google GenAI SDK at it and pass your Respan API key as the SDK’s key. If your code uses the OpenAI SDK, call Gemini models through Chat Completions instead.

POST https://gateway.respan.ai/v1beta/models/{model}:generateContent

Terminal
curl "https://gateway.respan.ai/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello!"}]}]}'

The gateway reads your Respan key from x-goog-api-key. For a stream, see Streaming.

Ways to reach Gemini

WayPathRouted, billed, and translatedKey for Google
Gemini API formatPOST /v1beta/models/{model}:generateContentYesRespan credits or your own
OpenAI formatPOST /v1/chat/completionsYesRespan credits or your own
Gemini passthroughPOST /api/google/gemini/v1beta/models/{model}:{action}No, only loggedYour own only

Gemini API format

These requests are routed like any other, so routes, BYOK, limits, and logging apply, and a model from another provider can answer in Gemini’s shape. To pin a provider, send the X-Respan-Route-Provider header.

Gemini-only fields with no equivalent elsewhere, such as safetySettings, cachedContent, and Google-run tools like googleSearch, reach Gemini models unchanged and are refused with 400 for other providers’ models. See known gaps.

Send Respan params in the X-Data-Respan-Params header, in a top-level respan_params object in the body, or in metadata.respan_params.

Streaming

Call :streamGenerateContent?alt=sse (the SDK’s generate_content_stream) and the gateway returns server-sent events in Gemini’s shape, whichever provider answers. Each event is a data: {GenerateContentResponse} with partial candidates, and the stream ends when the connection closes. Usage is in usageMetadata on the last chunk.

Terminal
curl -N "https://gateway.respan.ai/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Write a haiku about routers."}]}]}'

For errors before and during a stream, cancellation and billing, and the gateway’s fixed 600 second timeout, see Chat Completions.

Structured outputs

Gemini’s structured output setting is responseMimeType: application/json with a responseJsonSchema in generationConfig. It is also what the gateway sends to Gemini models when a Chat Completions request carries a json_schema response_format; a json_object format becomes responseMimeType: application/json alone. Gemini always enforces the schema strictly.

Terminal
curl "https://gateway.respan.ai/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Ada Lovelace was born in London in 1815."}]}],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseJsonSchema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "birth_year": {"type": "integer"},
          "city": {"type": "string"}
        },
        "required": ["name", "birth_year", "city"]
      }
    }
  }'

From Chat Completions, a json_schema with a description or strict: false is refused with 400 for Gemini models. See Model support. The gateway doesn’t repair JSON; see Invalid JSON.

Tool calling

Tools use Gemini’s shape: function definitions go in tools[].functionDeclarations, each with a name, a description and parameters. When the model calls one, the candidate’s content has a functionCall part with the name and args. Send the result back in the next request as a functionResponse part.

Terminal
curl "https://gateway.respan.ai/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "What is the weather in Paris?"}]}],
    "tools": [{
      "functionDeclarations": [{
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }]
    }]
  }'

The answer carries the call instead of text:

JSON
{"candidates": [{"content": {"role": "model", "parts": [
  {"functionCall": {"name": "get_weather", "args": {"city": "Paris"}}}
]}}]}

Google-run tools such as googleSearch reach Gemini models only; see Gemini API format. For the agent loop, tool_choice, routing by tool support, and how tool calls are logged and billed, see Tool calling on Chat Completions.

OpenAI format

Call a Gemini model from the OpenAI SDK by its catalog ID:

Python
response = client.chat.completions.create(
    model="gemini/gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)

The gateway calls Gemini on its native API, not Gemini’s OpenAI-compatible endpoint, so PDF and other file parts in messages work. OpenAI parameters are renamed for Gemini: max_tokens becomes max_output_tokens, n becomes candidate_count, stop becomes stop_sequences. See Parameters and Chat Completions.

Gemini passthrough

The passthrough sends your request body to Google’s Gemini API exactly as written. Use it when you need a Gemini feature the routed format can’t carry.

Python
client = genai.Client(
    api_key=os.environ["RESPAN_API_KEY"],
    http_options={"base_url": "https://gateway.respan.ai/api/google/gemini"},
)

With a Gemini key of your own (saved with BYOK or sent with the request), the call runs on it and the gateway only logs it, without routing, translating, or billing it. Without one, it runs on Respan credits on Gemini. See Passthrough.

Next steps