GenerateContentConfig.media_resolution = None leads to degraded vision performance

[msciancalepore98]

Applies for gemini-2.5 onwards: When I use GenerateContentConfig.media_resolution = None , vision performance is negatively impacted.
If I instead set it explicitly to types.MediaResolution.MEDIA_RESOLUTION_UNSPECIFIED, performance is good as usual. I found this by chance due to a refactor.

Our team internal bench suite shows a ~10% performance drop when using None; it's a 2-field data extraction task from ~1080p images.

Weird part is that token usage is the same as using MEDIA_RESOLUTION_UNSPECIFIED.

I didn't find any documentation showing the difference between None and MEDIA_RESOLUTION_UNSPECIFIED enum, so I always assumed they would be the same. They are not, apparently..?

At this point I've already solved the problem, but I'd like to have an explanation from someone that knows the internals.. out of curiosity. If hope that the media res enum has a good reason to be Optional and not default to MEDIA_RESOLUTION_UNSPECIFIED.
Plus, I hope this may help other people.

google.genai version == 1.57.0, python 3.10.8

[UniverseDragon14]

import os
from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from openai import OpenAI

Load .env

load_dotenv()

API_KEY = os.getenv("OPENAI_API_KEY")
if not API_KEY:
raise RuntimeError("OPENAI_API_KEY missing in .env")

client = OpenAI(api_key=API_KEY)

app = FastAPI(title="Universe Dragon • NOVA / DRAGON Backend")

Allow frontend access

app.add_middleware(
CORSMiddleware,
allow_origins=[""],
allow_credentials=False,
allow_methods=[""],
allow_headers=["*"],
)

===== PERSONAS =====

NOVA_INSTRUCTIONS = """
You are NOVA.
Tone: calm, intelligent, scientific, structured.
Explain clearly and deeply.
Assist in coding, research, and system design.
Use structured reasoning.
"""

DRAGON_INSTRUCTIONS = """
You are DRAGON.
Tone: powerful, direct, commanding.
Be concise.
Give steps.
Be decisive.
"""

===== Request Model =====

class ChatRequest(BaseModel):
mode: str
message: str

===== Chat Endpoint =====

@app.post("/api/chat")
def chat(req: ChatRequest):

mode = req.mode.lower().strip()

if mode not in ["nova", "dragon"]:
    raise HTTPException(status_code=400, detail="Mode must be nova or dragon")

system_prompt = NOVA_INSTRUCTIONS if mode == "nova" else DRAGON_INSTRUCTIONS

try:
    response = client.responses.create(
        model="gpt-4.1-mini",
        input=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": req.message}
        ],
    )

    return {"reply": response.output_text}

except Exception as e:
    raise HTTPException(status_code=500, detail=str(e))
    import os

from dotenv import load_dotenv

from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel, Field

from openai import OpenAI

load_dotenv()

API_KEY = os.getenv("OPENAI_API_KEY")
if not API_KEY:
raise RuntimeError("OPENAI_API_KEY is missing. Put it in .env or export it in your shell.")

client = OpenAI(api_key=API_KEY)

app = FastAPI(title="Universe Dragon • NOVA/DRAGON Backend")

If you open the UI from a different origin (e.g., phone), CORS helps.

If you serve UI from this same FastAPI app, CORS isn’t strictly required—but it’s convenient.

app.add_middleware(
CORSMiddleware,
allow_origins=[""],
allow_credentials=False,
allow_methods=[""],
allow_headers=["*"],
)

--- Personas ---

NOVA_INSTRUCTIONS = """You are NOVA.
Tone: calm, intelligent, detailed, scientific. Explain clearly and deeply.
You assist in coding, research, and system analysis.
Always provide structured steps and the next concrete action."""
DRAGON_INSTRUCTIONS = """You are DRAGON.
Tone: powerful, direct, tactical.
Focus on execution, commands, and exact steps. Minimal fluff.
When relevant, output terminal commands and file edits precisely."""

class ChatIn(BaseModel):
mode: str = Field(..., pattern="^(nova|dragon)$")
message: str = Field(..., min_length=1, max_length=8000)

class ChatOut(BaseModel):
reply: str

@app.post("/api/chat", response_model=ChatOut)
def chat(payload: ChatIn):
instructions = NOVA_INSTRUCTIONS if payload.mode == "nova" else DRAGON_INSTRUCTIONS

try:
# Responses API: recommended for new projects
# We keep it stateless for simplicity: instructions + user input
resp = client.responses.create(
model="gpt-5",
instructions=instructions,
input=payload.message,
)

reply_text = getattr(resp, "output_text", None) or ""
if not reply_text.strip():
  reply_text = "(No text output received.)"

return ChatOut(reply=reply_text)

except Exception as e:
raise HTTPException(status_code=500, detail=str(e))

<title>UNIVERSE DRAGON • NOVA / DRAGON</title> <style> :root{ --bg:#05060b; --panel: rgba(12,14,22,.78); --line: rgba(255,255,255,.10); --txt:#eef2ff; --muted: rgba(238,242,255,.65); --blue:#46b6ff; --orange:#ff8a2a; --good:#34f3b2; --shadow: 0 18px 55px rgba(0,0,0,.45); --blur: blur(14px); } *{box-sizing:border-box} body{ margin:0; min-height:100vh; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; color:var(--txt); background: radial-gradient(1100px 600px at 20% 15%, rgba(70,182,255,.18), transparent 60%), radial-gradient(900px 520px at 85% 25%, rgba(255,138,42,.16), transparent 60%), radial-gradient(900px 520px at 45% 90%, rgba(52,243,178,.10), transparent 55%), var(--bg); overflow-x:hidden; } .wrap{ max-width: 980px; margin: 28px auto; padding: 0 14px; } header{ display: