Gemini API thinking_budget와 thinking_level 충돌 오류를 해결하는 3가지 방법

Gemini 3.0 Pro Preview 또는 gemini-3-flash-preview 모델을 호출할 때 thinking_budget and thinking_level are not supported together 오류를 겪고 계신가요? 이것은 Google Gemini API의 모델 버전 간 파라미터 업데이트로 인해 발생하는 호환성 문제입니다. 본 포스팅에서는 API 설계의 진화 관점에서 이 오류의 근본 원인과 올바른 설정 방법을 체계적으로 분석해 보겠습니다.

핵심 가치: 이 글을 읽고 나면 Gemini 2.5 및 3.0 모델의 사고 모드(Thinking Mode) 파라미터를 설정하는 올바른 방법을 완벽히 이해하게 됩니다. 이를 통해 흔히 발생하는 API 호출 오류를 방지하고, 대규모 언어 모델의 추론 성능과 비용 제어를 최적화할 수 있습니다.

Gemini API 사고 모드 파라미터 진화 핵심 요점

Gemini 사고 모드 파라미터 핵심 차이

Google이 Gemini 3.0에서 thinking_level 파라미터를 도입한 핵심적인 이유는 개발자의 설정 경험을 간소화하기 위해서입니다. Gemini 2.5의 thinking_budget은 개발자가 사고 토큰 수를 정밀하게 추산해야 했지만, Gemini 3.0의 thinking_level은 이러한 복잡성을 4개의 시맨틱(Semantic) 등급으로 추상화하여 설정 진입 장벽을 낮췄습니다.

이러한 설계 변화는 API 진화 과정에서의 트레이드오프를 반영합니다. 즉, 일부 세밀한 제어 기능을 희생하는 대신 더 나은 사용 편의성과 모델 간 일관성을 확보한 것이죠. 대부분의 응용 시나리오에서는 thinking_level의 추상화만으로도 충분하며, 극도로 비용을 최적화해야 하거나 특정 토큰 예산 제어가 필요한 경우에만 thinking_budget을 사용하면 됩니다.

💡 기술 팁: 실제 개발 시에는 APIYI(apiyi.com) 플랫폼을 통해 인터페이스 호출 테스트를 진행해 보시는 것을 권장합니다. 이 플랫폼은 통합 API 인터페이스를 제공하여 Gemini 2.5 Flash, Gemini 3.0 Pro, Gemini 3.0 Flash 등 다양한 모델을 지원하며, 서로 다른 사고 모드 설정에 따른 실제 효과와 비용 차이를 빠르게 검증하는 데 매우 유용합니다.

오류의 근본 원인: 매개변수 설계의 전방 호환성 전략

API 오류 메시지 분석

{
  "status_code": 400,
  "error": {
    "message": "Unable to submit request because thinking_budget and thinking_level are not supported together.",
    "type": "upstream_error",
    "code": 400
  }
}

이 오류의 핵심은 thinking_budget과 thinking_level을 동시에 사용할 수 없다는 점이에요. Google은 Gemini 3.0에서 새로운 매개변수를 도입하면서 기존 매개변수를 완전히 삭제하지 않고, 대신 서로 배타적으로 작동하게 하는 전략을 선택했습니다.

• Gemini 2.5 모델: thinking_budget만 수용하며, thinking_level은 무시합니다.
• Gemini 3.0 모델: thinking_level을 우선적으로 사용합니다. 하위 호환성을 위해 thinking_budget도 수용하긴 하지만, 두 매개변수를 동시에 전달하는 것은 허용하지 않습니다.
• 오류 발생 조건: API 요청에 thinking_budget과 thinking_level이 모두 포함된 경우.

왜 이런 오류가 발생할까요?

개발자가 이 오류를 겪게 되는 상황은 보통 다음 세 가지 중 하나입니다.

🎯 선택 가이드: Gemini 모델 버전을 전환할 때는 먼저 APIYI(apiyi.com) 플랫폼에서 매개변수 호환성을 테스트해보는 것을 추천해요. 이 플랫폼은 Gemini 2.5 및 3.0 시리즈 모델 간의 빠른 전환을 지원하므로, 운영 환경에서 매개변수 충돌을 겪기 전에 다양한 사고 모드 설정에 따른 응답 품질과 지연 시간 차이를 미리 비교해볼 수 있습니다.

3가지 해결 방법: 모델 버전에 맞는 올바른 매개변수 선택하기

방법 1: Gemini 2.5 모델 설정 (thinking_budget 사용)

적용 모델: gemini-2.5-flash, gemini-2.5-pro 등

매개변수 설명:

• thinking_budget: 0 – 사고 모드를 완전히 비활성화하여 지연 시간과 비용을 최소화합니다.
• thinking_budget: -1 – 동적 사고 모드. 모델이 요청의 복잡도에 따라 자동으로 조정합니다.
• thinking_budget: <양의 정수> – 사고 토큰 수의 상한선을 정확하게 지정합니다.

간단 예시

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "양자 얽힘의 원리를 설명해줘"}],
    extra_body={
        "thinking_budget": -1  # 동적 사고 모드
    }
)
print(response.choices[0].message.content)

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "양자 얽힘의 원리를 설명해줘"}],
    extra_body={
        "thinking_budget": -1,  # 동적 사고 모드
        "include_thoughts": True  # 사고 요약 반환 활성화
    }
)

# 사고 내용 추출 (활성화된 경우)
for part in response.choices[0].message.content:
    if hasattr(part, 'thought') and part.thought:
        print(f"사고 과정: {part.text}")

# 최종 답변 추출
final_answer = response.choices[0].message.content
print(f"최종 답변: {final_answer}")

참고: Gemini 2.5 모델은 2026년 3월 3일에 중단될 예정이므로, 가급적 빨리 Gemini 3.0 시리즈로 마이그레이션하는 것이 좋습니다. APIYI(apiyi.com) 플랫폼을 통해 마이그레이션 전후의 응답 품질 차이를 쉽게 확인해 보세요.

방법 2: Gemini 3.0 모델 설정 (thinking_level 사용)

적용 모델: gemini-3.0-flash-preview, gemini-3.0-pro-preview

매개변수 설명:

• thinking_level: "minimal" – 최소 사고. 예산이 거의 없는 것과 같으며, 사고 서명(Thought Signatures) 전달이 필요합니다.
• thinking_level: "low" – 낮은 강도의 사고. 간단한 지시 준수나 채팅 상황에 적합합니다.
• thinking_level: "medium" – 중간 강도의 사고. 일반적인 추론 작업에 적합합니다. (Gemini 3.0 Flash만 지원)
• thinking_level: "high" – 높은 강도의 사고. 추론 깊이를 극대화하며 복잡한 문제 해결에 적합합니다. (기본값)

간단 예시

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "이 코드의 시간 복잡도를 분석해줘"}],
    extra_body={
        "thinking_level": "medium"  # 중간 강도 사고
    }
)
print(response.choices[0].message.content)

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# 첫 번째 대화
response_1 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "LRU 캐시 알고리즘을 설계해줘"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# 사고 서명 추출 (Gemini 3.0은 자동으로 반환합니다)
thought_signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        thought_signatures.append(part.thought_signature)

# 두 번째 대화: 추론 체인을 유지하기 위해 사고 서명 전달
response_2 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[
        {"role": "user", "content": "LRU 캐시 알고리즘을 설계해줘"},
        {"role": "assistant", "content": response_1.choices[0].message.content, "thought_signatures": thought_signatures},
        {"role": "user", "content": "이 알고리즘의 공간 복잡도를 최적화해봐"}
    ],
    extra_body={
        "thinking_level": "high"
    }
)
print(response_2.choices[0].message.content)

💰 비용 최적화: 예산에 민감한 프로젝트라면 APIYI(apiyi.com)를 통해 Gemini 3.0 Flash API를 호출해 보세요. 이 플랫폼은 유연한 과금 방식과 경쟁력 있는 가격을 제공하여 소규모 팀이나 개인 개발자에게 적합합니다. 여기에 thinking_level: "low"를 함께 사용하면 비용을 더욱 절감할 수 있어요.

방법 3: 동적 모델 전환을 위한 매개변수 적응 전략

적용 상황: 코드 하나에서 Gemini 2.5와 3.0 모델을 동시에 지원해야 할 때

지능형 매개변수 적응 함수

def get_thinking_config(model_name: str, complexity: str = "medium") -> dict:
    """
    모델 버전에 따라 올바른 사고 모드 매개변수를 자동으로 선택합니다.

    Args:
        model_name: Gemini 모델 이름
        complexity: 사고 복잡도 ("minimal", "low", "medium", "high", "dynamic")

    Returns:
        extra_body에 사용할 매개변수 딕셔너리
    """
    # Gemini 3.0 모델 리스트
    gemini_3_models = [
        "gemini-3.0-flash-preview",
        "gemini-3.0-pro-preview",
        "gemini-3-flash",
        "gemini-3-pro"
    ]

    # Gemini 2.5 모델 리스트
    gemini_2_5_models = [
        "gemini-2.5-flash-preview-04-17",
        "gemini-2.5-flash-lite",
        "gemini-2-flash",
        "gemini-2-flash-lite"
    ]

    # 모델 버전 판단
    if any(m in model_name for m in gemini_3_models):
        # Gemini 3.0은 thinking_level 사용
        level_map = {
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"  # 기본값으로 고강도 설정
        }
        return {"thinking_level": level_map.get(complexity, "medium")}

    elif any(m in model_name for m in gemini_2_5_models):
        # Gemini 2.5는 thinking_budget 사용
        budget_map = {
            "minimal": 0,
            "low": 512,
            "medium": 2048,
            "high": 8192,
            "dynamic": -1
        }
        return {"thinking_budget": budget_map.get(complexity, -1)}

    else:
        # 알 수 없는 모델의 경우 Gemini 3.0 매개변수를 기본값으로 사용
        return {"thinking_level": "medium"}

# 사용 예시
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

model = "gemini-3.0-flash-preview"  # 동적으로 전환 가능
thinking_config = get_thinking_config(model, complexity="high")

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "질문 내용"}],
    extra_body=thinking_config
)

🚀 빠른 시작: APIYI(apiyi.com) 플랫폼을 사용하여 프로토타입을 빠르게 구축해 보세요. 별도의 복잡한 설정 없이 바로 사용할 수 있는 Gemini API 인터페이스를 제공하며, 클릭 한 번으로 다양한 사고 모드 매개변수를 전환하며 효과를 비교해 볼 수 있습니다. 단 5분이면 연동이 끝납니다!

Gemini 3.0 생각 서명 (Thought Signatures) 메커니즘 상세 가이드

생각 서명이란 무엇인가요?

Gemini 3.0에서 도입된 **생각 서명(Thought Signatures)**은 모델 내부의 추론 과정을 암호화하여 나타낸 것입니다. include_thoughts: true 설정을 활성화하면 모델은 응답과 함께 추론 과정의 암호화된 서명을 반환합니다. 이후 이어지는 대화에서 이 서명을 다시 전달하면, 모델이 이전의 추론 체인을 일관성 있게 유지하며 대화를 이어갈 수 있습니다.

핵심 특징:

• 암호화된 표현: 서명 내용은 사람이 읽을 수 없으며, 오직 모델만이 해석할 수 있습니다.
• 추론 체인 유지: 멀티턴 대화에서 서명을 전달함으로써 모델이 이전의 사고 과정을 바탕으로 계속해서 추론할 수 있게 합니다.
• 강제 반환: Gemini 3.0은 요청하지 않더라도 기본적으로 생각 서명을 반환합니다.

생각 서명의 실제 활용 시나리오

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# 1단계: 모델에게 알고리즘 설계를 요청합니다
response_1 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[{"role": "user", "content": "분산 처리 환경에서의 속도 제한(Rate Limiting) 알고리즘을 설계해 줘"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# 생각 서명 추출
signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        signatures.append(part.thought_signature)

# 2단계: 이전의 추론을 기반으로 계속해서 최적화 진행
response_2 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[
        {"role": "user", "content": "분산 처리 환경에서의 속도 제한(Rate Limiting) 알고리즘을 설계해 줘"},
        {
            "role": "assistant",
            "content": response_1.choices[0].message.content,
            "thought_signatures": signatures  # 생각 서명 전달
        },
        {"role": "user", "content": "분산 환경의 시계 불일치 문제는 어떻게 해결할 수 있을까?"}
    ],
    extra_body={"thinking_level": "high"}
)

💡 베스트 프랙티스: 시스템 설계, 알고리즘 최적화, 코드 리뷰와 같이 여러 단계의 복잡한 추론이 필요한 상황에서는 APIYI(apiyi.com) 플랫폼을 통해 생각 서명 전달 유무에 따른 효과 차이를 테스트해 보시는 것을 추천합니다. 해당 플랫폼은 Gemini 3.0의 생각 서명 메커니즘을 완벽하게 지원하므로, 다양한 설정값에 따른 추론 품질을 간편하게 검증할 수 있습니다.

자주 묻는 질문 (FAQ)

# thinking_level만 전달하여 응답 관찰
response = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "test"}],
    extra_body={"thinking_level": "low"}
)
# 만약 400 에러가 발생하면서 thinking_level을 지원하지 않는다는 메시지가 뜨면 Gemini 2.5입니다.

요약

Gemini API의 thinking_budget 및 thinking_level 관련 오류를 방지하기 위한 핵심 요점은 다음과 같아요.

1. 파라미터 상호 배타성: Gemini 2.5는 thinking_budget을 사용하고, Gemini 3.0은 thinking_level을 사용합니다. 이 두 파라미터를 동시에 전달해서는 안 됩니다.
2. 모델 식별: 모델 이름을 통해 버전을 확인해야 해요. 2.5 시리즈라면 thinking_budget을, 3.0 시리즈라면 thinking_level을 적용해 주세요.
3. 동적 어댑터 활용: 모델 이름에 따라 올바른 파라미터를 자동으로 선택해 주는 어댑터 함수를 사용해 보세요. 하드코딩을 피하는 가장 좋은 방법입니다.
4. 추론 시그니처(Thinking Signature): Gemini 3.0에는 추론 시그니처 메커니즘이 새롭게 도입되었어요. 여러 차례 대화가 이어지는 복잡한 추론 시나리오에서는 추론 체인을 유지하기 위해 이 시그니처를 함께 전달해야 합니다.
5. 마이그레이션 권고: Gemini 2.5는 2026년 3월 3일에 서비스가 종료될 예정이에요. 따라서 가급적 빨리 3.0 시리즈로 전환하시는 것을 추천드려요.

다양한 사고 모드(Thinking Mode) 설정의 실제 효과를 직접 확인해 보고 싶다면 **APIYI(apiyi.com)**를 통해 빠르게 검증해 보세요. 이 플랫폼은 Gemini 전 시리즈 모델을 지원하며, 통합 인터페이스와 유연한 과금 방식을 제공하여 비교 테스트부터 실제 서비스 배포까지 최적의 환경을 제공합니다.

작성자: APIYI 기술 팀 | 기술적인 궁금증이 있으시다면 언제든 APIYI(apiyi.com)를 방문하여 다양한 AI 모델 연동 솔루션을 확인해 보세요.