Gemini 4 Carbon API 마이그레이션: 400 오류, 시간 초과, 출력 한도

Gemini 4 Carbon은 요청 스키마 수준에서 Gemini 4 Argon을 그대로 대체할 수 있습니다. 동일한 채팅 완료 요청 본문을 사용할 수 있으며, 모델 ID만 바꾸면 됩니다. 다만 일부 매개변수 값은 그대로 적용되지 않습니다. 주의해야 할 실패는 한 단계 아래에 있습니다. 400을 반환하는 매개변수 오류, 조용히 잘리는 출력 한도, 그리고 긴 사고 과정을 전제로 한 시간 초과 및 과금 방식입니다.

첫 주를 좌우하는 기본 설정은 네 가지입니다.

• AIHubMix에서는 max_tokens를 65,536 이하로 유지하세요. 게이트웨이는 Chat Completions만 문서화했으며, 더 큰 출력을 위한 경로는 공개하지 않았습니다.
• Google 네이티브 Interactions/백그라운드 실행에서는 store=true와 명시적인 max_output_tokens를 설정하세요. AIHubMix에서는 Carbon에 이 필드가 문서화되어 있지 않습니다.
• 공급업체 네이티브 장시간 디코딩 경로를 사용하는 경우, 스트림별 HTTP 읽기 시간 제한을 15~20분으로 늘리세요.
• 무시되는 temperature, top_p, top_k와 페널티 매개변수는 제거하세요. Google의 Carbon 가이드에 따르면 candidate_count를 1보다 크게 설정하면 400 오류가 반환됩니다.

변경되지 않은 기본 사항인 액세스, 보안상 거부, 작업당 비용은 Argon 마이그레이션 게시물을 참고하세요. 이 게시물에서는 Carbon에만 해당하는 동작을 다룹니다.

명확한 오류와 조용한 실패

실패 양상은 뚜렷하게 나뉩니다. 400 오류는 즉시 알려 주지만, 조용한 한도 초과는 청구서에서야 알 수 있습니다.

AIHubMix는 gemini-4-carbon의 가격을 입력 토큰 백만 개당 $2, 출력 토큰 백만 개당 $10, 캐시 토큰 백만 개당 $0.10으로 표시하고 있습니다. 이는 Google의 프로모션 요금이며, Chat Completions를 통해 제공됩니다. 요금은 한시적입니다. 과금 내용을 확인하세요.

명확한 오류: 문서화된 400 오류

문서화된 400 오류 중 상당수는 매개변수 검증 오류이며, 대화 기록과 미리 채워진 모델 턴은 요청 상태 오류입니다. 아래 규칙은 별도 표기가 없는 한 Google의 네이티브 Carbon 가이드에서 가져온 것입니다. 현재 AIHubMix는 Carbon에 대해 Chat Completions만 문서화하고 있습니다. AIHubMix의 Carbon 안내에는 다음과 같이 한 줄로 설명되어 있습니다. "400 — 매개변수 오류. 대부분 상위 공급자에서 그대로 전달됩니다." 이는 게이트웨이에 대한 설명이지 테스트 결과가 아닙니다. 자세한 내용은 Google의 Carbon 가이드와 새로운 기능 페이지를 참고하세요.

Google은 "백그라운드 상호작용에는 store=true가 필요합니다."라는 메시지를 그대로 표시합니다. * Google 네이티브에만 해당: max_output_tokens는 최대 1M으로 제한되며, 백그라운드 실행에는 store=true가 필요합니다. AIHubMix는 이 경로를 문서화하지 않았습니다. AIHubMix의 Chat Completions 경로에서는 ≤65K를 사용하세요.

minimal에는 두 가지 의미가 있습니다. Google 네이티브 Carbon 필드에서는 thinking_budget과 thinking_level=MINIMAL을 사용하면 HTTP 400 오류가 반환되므로 low, medium 또는 high를 사용하세요. Google의 OpenAI 호환성 계층에서는 reasoning_effort=minimal이 low로 매핑됩니다. AIHubMix는 Carbon에 이 매핑을 적용하는지 공개하지 않았습니다.

도구 처리도 관련된 함정입니다. Google의 Carbon 가이드에서는 도구 실행 턴을 순차적으로 처리하는 방식을 권장하고, AIHubMix의 Gemini 가이드에는 tool_choice="auto"가 문서화되어 있습니다. 게이트웨이에서 Carbon의 도구 지원 여부는 아직 확인되지 않았습니다.

/v1/chat/completions에서 사용할 수 있는 가장 단순하고 안전한 요청은 Carbon이 무시하는 항목을 제거합니다.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key=os.environ["AIHUBMIX_API_KEY"],
)

response = client.chat.completions.create(
    model="gemini-4-carbon",
    messages=[{"role": "user", "content": "Reply with OK."}],
    max_tokens=32768,  # room for thinking plus answer
)
print(response.choices[0].message.content)

이 요청이 200을 반환하면 전송 계층은 문제없이 작동하는 것입니다. 나머지는 오류를 일으키지 않는 응답에 관한 내용입니다.

조용한 실패: 오류는 없지만 출력이 잘못되고 청구 금액도 달라짐

표준 출력 한도는 65,536이며, 공급업체 장시간 디코딩은 별도 경로입니다

Carbon의 표준 출력 한도는 65,536토큰입니다. Chat Completions에서 한도 필드는 max_tokens이고, Google의 네이티브 가이드에서는 max_output_tokens라고 부릅니다. Google 네이티브 장시간 디코딩 경로에서는 입력을 제외하고 최대 1,048,576토큰까지 출력할 수 있으며, 131,072와 262,144가 그 예입니다. Google의 새로운 기능 페이지에는 다음과 같이 규칙이 명시되어 있습니다. "max_output_tokens를 정의하지 않고 background: true로 설정하면 서버는 64K 토큰 이후에 처리를 중단합니다." AIHubMix는 Carbon의 백그라운드 실행이나 이어 생성 기능을 문서화하지 않았습니다.

공급업체 네이티브 장시간 디코딩은 여러 구간으로 실행됩니다. 백그라운드 또는 스트리밍 모드에서는 홉당 64K, 비스트리밍 모드에서는 홉당 32K이며, 비스트리밍 REST 요청 하나는 32,768토큰에서 멈춥니다. Google 가이드에는 "이전 SDK 버전과 OpenAI 호환성 계층에서는 이어쓰기 토큰을 사용해 긴 응답을 가져올 수 없습니다."라고 나와 있습니다. AIHubMix에서는 보수적인 미확인 게이트웨이 한도로 간주해 max_tokens를 65,536 이하로 유지하세요. 모델 페이지에 관련 내용이 명시되기 전까지는 더 긴 응답을 이어 붙이는 방식으로 계획하지 마세요.

한도가 낮으면 사고 과정이 잘리고, 빈 출력도 과금됩니다

출력 한도에는 텍스트뿐 아니라 사고 과정도 포함됩니다. Google의 장시간 디코딩 가이드에는 "8,192와 같이 값이 낮으면 모델이 사고를 마치기 전에 처리가 중단됩니다."라고 나와 있습니다. 상태는 incomplete가 되고, "모델이 여전히 사고 중이었다면 텍스트가 비어 있을 수 있습니다." 어느 경우든 비용은 청구됩니다. 사고 과정과 응답을 모두 감안해 예산을 잡고, 출력이 비어 있는 incomplete 응답은 한도 문제로 간주하세요. 한도를 늘리고 재시도하되, 첫 번째 시도도 청구서에 포함된다는 점을 고려해야 합니다.

사고 모드 기본값은 medium입니다

Carbon의 기본값은 Argon과 동일한 medium입니다. 기본값이 high인 Gemini 3.1 Pro Preview에서 전환하는 팀은 코드를 바꾸지 않아도 사고 수준이 한 단계 낮아지므로, 응답이 얕아진 것을 성능 저하로 오해할 수 있습니다. Google은 대부분의 코딩 및 에이전트 작업에 medium을 권장합니다. 스테이징에서 수준을 명시적으로 설정하고, 제어 필드는 하나만 전송하세요. reasoning_effort와 thinking_level은 함께 사용할 수 없습니다.

샘플링 매개변수는 무시됩니다

temperature, top_p, top_k는 무시됩니다. 오류도 발생하지 않고 샘플도 달라지지 않습니다. 제거하세요. 페널티 매개변수와 1보다 큰 candidate_count 값은 400 오류를 반환합니다.

명시적 캐싱은 지원되지 않습니다

cachedContents와 caches.create는 지원되지 않습니다. 4,096토큰 이상에서는 암시적 캐싱이 적용되며 95% 할인이 제공됩니다. 명시적 캐시 관련 코드를 삭제하고, 안정적인 프롬프트 접두부를 앞에 두며, 할인율을 예산에 반영하기 전에 캐시된 토큰 사용량을 확인하세요.

대화 상태에는 규칙이 있습니다

Google은 이어서 대화할 때 previous_interaction_id를 권장합니다. Chat Completions에는 이 필드가 없으므로 대화 기록을 유지하되 사용자 턴으로 끝내세요. 모델 역할로 끝나는 기록이나 미리 채워진 모델 턴은 지원되지 않습니다.

시간 초과: 60초가 아니라 15~20분

Google의 장시간 디코딩 가이드는 스트림별 HTTP 읽기 시간 제한으로 15~20분을 권장하며, 마이그레이션 체크리스트에서도 최소 15분을 반복해서 안내합니다. 이 권고는 장시간 디코딩 요청에 관한 것입니다. 별도의 AA 측정에서는 첫 응답 토큰이 도착하기까지 걸린 시간이 Carbon High에서 67.1초, Medium에서 23.2초, Low에서 12.9초, Argon High에서 40.1초였습니다. 시간 제한을 60초로 설정하면 첫 토큰이 도착하기는 할까요?

이 측정에서 Carbon High는 60초 기준을 넘습니다. 첫 토큰 도착 시간만으로 전체 요청에 적합한 시간 제한을 알 수는 없습니다. 위의 15~20분 권고는 Google의 장시간 디코딩 가이드에서 나온 것입니다. 이는 한 시점의 측정 결과일 뿐, 지연 시간 보장이나 AIHubMix 테스트 결과가 아닙니다.
Google 네이티브 클라이언트의 홉 시간 제한은 백그라운드 시간 제한보다 짧습니다. 스트리밍은 20분, 비스트리밍 호출은 10분이며, 백그라운드는 24시간입니다. AIHubMix는 이러한 백그라운드 제한을 문서화하지 않았습니다.

장시간 디코딩에 필요한 네이티브 SDK 최소 버전: Python 2.34.0, JS 2.32.0, Go 1.77.0, Java 1.80.0, .NET 1.28.0. Claude Code의 API_TIMEOUT_MS 기본값은 10분입니다. 향후 Carbon에서 Claude Code 경로가 지원되는 것으로 확인되면 첫 실행 전에 값을 늘리세요.

과금 관련 함정

Carbon의 토큰당 가격은 간단하지만 청구 금액은 그렇지 않습니다. 몇 가지 요인으로 청구 금액이 커지고, 예정된 요금 변경 한 번으로 모든 요금이 두 배가 됩니다.

사고 과정도 출력으로 과금됩니다

사고 토큰은 출력으로 과금됩니다. 현재 Carbon의 출력 요금은 토큰 백만 개당 $10이며, 12월 1일부터는 $20입니다.

장시간 디코딩 홉마다 과금됩니다

Google의 계산 예시에서는 1,000토큰 프롬프트로 출력 토큰 200,000개를 생성할 때 홉별 토큰 수가 1,000, 66,536, 132,072, 197,608로 나타나며 total_input_tokens은 397,216입니다. "사고 과정만 포함된 홉을 포함해 모든 홉의 모든 토큰에 대해 비용이 청구됩니다." 암시적 캐싱으로 대부분의 입력 토큰에 95% 할인이 적용되지만, 홉은 계속 사용량에 포함됩니다. 실행이 실패하거나 취소되어도 완료된 작업은 과금됩니다. "나중 구간이 실패하거나 취소되더라도 완료된 구간은 각 구간이 끝날 때 과금됩니다." 또한 "상호작용이 끝나기 전에 완료된 모든 작업에 대해 비용이 청구됩니다."

그라운딩은 별도로 과금됩니다

Google 네이티브 서비스에서 Google Search를 사용하는 그라운딩은 월 5,000건의 무료 요청을 제공하며, Gemini 3 및 이후 모델과 한도를 공유합니다. 이후에는 1,000건당 $14가 부과되며, 일일 한도는 1,500건입니다. AIHubMix는 Carbon의 그라운딩을 문서화하지 않았습니다.

Vertex의 각주는 공급업체 서비스에만 해당합니다

Google의 Vertex 가격 페이지에는 32K 토큰을 초과하는 완료 요청이 클라이언트 또는 서버 시간 초과로 실패하더라도 가져올 수 있는 토큰 사용량에 대해 요금이 부과된다는 규칙이 추가되어 있습니다. 이 규칙은 2026년 11월 13일부터 적용됩니다. 이는 공급업체의 규칙이며, AIHubMix의 VertexAI 공급자가 이를 적용하는지는 공개되지 않았습니다. 당연히 적용된다고 가정하기 전에 문의하세요.

12월 1일부터 모든 요금이 두 배로 인상됩니다

Carbon과 Argon은 동일한 프로모션 요금을 적용받으며, 12월 1일에 모든 요금이 두 배로 인상됩니다. 현재 AIHubMix는 프로모션 요금을 표시하고 있으며, 12월 이후 가격은 공개하지 않았습니다. 요금이 두 배가 된다는 점은 확정으로, 게이트웨이 가격은 미정으로 간주하고 예산을 확정하기 전에 두 가지를 모두 확인하세요.

실제 권한이 있는 에이전트

Google 네이티브 호출의 경우 Carbon 가이드에서는 도구를 순차적으로 실행하는 턴을 권장합니다. 이 경로를 사용할 때는 한 번에 하나씩 호출을 구성하세요. AIHubMix의 Gemini 가이드에는 tool_choice="auto"가 문서화되어 있지만, 게이트웨이에서 Carbon별 도구 지원과 도구 강제 동작이 가능한지는 확인되지 않았습니다.

대화 기록은 모델 턴으로 끝나면 안 되며, 미리 채워진 모델 턴은 지원되지 않습니다. 도구 결과가 누락되면 다음 단계를 요청하는 사용자 턴을 보내세요.

모델 카드에는 간헐적인 속도 저하나 시간 초과, 높은 수준에서의 추가 토큰 사용이 명시되어 있습니다. 지식 기준일은 2026년 3월입니다. 쓰기 권한이 있다면 시간 초과가 실질적인 위험입니다. 실행이 클라이언트 제한 시간을 넘으면 작업이 일부만 반영된 채 남을 수 있고, 완료된 세그먼트에도 요금이 부과됩니다.

코딩 도구: 연결하기 전에 모델 페이지를 확인하세요

AIHubMix의 Carbon 목록에는 Chat Completions만 문서화되어 있으며, Carbon은 아직 공개 모델 색인에 없습니다. Claude Code에는 Anthropic Messages가 필요하고 Codex에는 Responses가 필요합니다. AIHubMix에서 Carbon용으로 어느 쪽도 지원되는지는 확인되지 않았습니다. 둘 중 어느 하나가 작동한다고 가정하지 마세요. 위에 링크된 Carbon 모델 페이지를 열어 프로토콜 목록을 확인하세요. Chat Completions만 표시된다면 OpenAI 호환 클라이언트를 사용하거나 기다리세요.

요청 형식은 Argon과 같지만 프로토콜 가용성은 다릅니다. 현재 AIHubMix에는 Carbon의 Chat Completions만 문서화되어 있습니다. Claude Code 게시물에서는 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, API_TIMEOUT_MS를 다루고, Codex 게시물에서는 공급자 블록, wire_api, model_reasoning_effort를 다룹니다. 달라지는 점은 해당 프로토콜이 존재하는지 여부입니다.

설정:

• 모델 ID: gemini-4-carbon.
• 사고 모드: low, medium, high. 기본값은 medium입니다.
• 추론 수준 매핑: 네이티브 필드는 thinking_level, 호환 필드는 reasoning_effort입니다. Google은 추론 수준 값을 매핑하지만, AIHubMix는 Carbon의 매핑을 공개하지 않았습니다. 한 가지 방식으로 전송하세요.
• 컨텍스트: Google 기준 1,048,576입니다. AIHubMix는 Carbon의 한도를 공개하지 않았으므로 공급업체 수치를 기준으로 구축하지 마세요.
• 알려진 문제: high에서 첫 토큰이 느리게 생성될 수 있음, 공급업체는 순차적 도구 턴을 권장함, 검증되지 않은 AIHubMix의 보수적 출력 토큰 한도 65,536, 지식 기준일 2026년 3월.

스모크 테스트, 10~15분:

1. 실패하는 단위 테스트 하나와 1분 이내에 끝나는 테스트 명령이 있는 작은 저장소를 선택하세요.
2. 모델을 gemini-4-carbon으로, max_tokens를 65,536 이하로 설정하고 HTTP 시간 제한은 최소 15분으로 설정하세요.
3. 테스트를 통과시키는 최소한의 변경을 도구에 요청한 다음, 테스트 명령을 실행하고 diff를 확인하세요.
4. 통과: 수정이 최소한이고 테스트가 10~15분 안에 통과합니다. 실패: 응답이 400 오류였는지, 불완전한 답변이었는지, 시간 초과였는지, 잘못된 수정이었는지 기록하세요. 각각 해결 방법이 다릅니다.
5. 도구에서 수준을 설정할 수 있다면 medium과 high를 테스트하고, 제한 시간 안에 완료되는 수준을 선택하세요.

첫 프로덕션 요청 전 체크리스트

• 모델 ID를 gemini-4-carbon으로 설정.
• temperature, top_p, top_k를 사용하지 않음.
• frequency_penalty 또는 presence_penalty를 사용하지 않음. candidate_count는 1로 유지하거나 생략.
• max_tokens를 65,536 이하로 설정.
• Google 네이티브 백그라운드 요청에는 store=true와 명시적인 max_output_tokens를 지정합니다. AIHubMix는 이 경로를 문서화하지 않았습니다.
• HTTP 시간 제한은 15분 이상으로 설정하고, 스트리밍을 권장합니다.
• reasoning_effort와 thinking_level 중 하나만 사용.
• Google 네이티브에서는 순차적 도구 턴을 권장합니다. AIHubMix에는 tool_choice="auto"가 문서화되어 있지만 Carbon 지원은 확인되지 않았습니다.
• 명시적인 캐시 호출은 하지 말고 안정적인 프롬프트 접두부를 먼저 배치합니다.
• 예산에는 사고 토큰과 모든 장시간 디코딩 단계의 비용을 포함합니다.
• 12월 1일 요금은 예산 담당자와 확인했습니다.
• 설정 전에 모델 페이지에서 코딩 도구를 확인했습니다.

자주 묻는 질문

Argon에서 Carbon으로 옮길 때 요청 본문을 변경해야 하나요?
아니요. 스키마는 바뀌지 않습니다. 모델 ID를 변경하고 값들을 검토한 다음, 이제 400 오류를 반환하는 필드를 제거하세요.

max_output_tokens가 400 오류를 반환하는 이유는 무엇인가요?
Google의 네이티브 Carbon API는 1,048,576을 초과하는 값을 거부합니다. AIHubMix의 Chat Completions 경로에는 별도의 보수적인 권장 사항이 있습니다. 더 큰 한도가 문서화될 때까지 max_tokens를 65,536 이하로 유지하세요. 값을 낮게 설정하면 대신 사고가 잘립니다. 이는 더 나쁜 결과를 낳습니다. 답변이 불완전해지고 요금은 부과될 수 있습니다.

응답이 비어 있는 이유는 무엇인가요?
상태가 불완전이라면 모델이 아직 사고 중이어서 텍스트가 비어 있을 수 있습니다. 작업 비용은 부과됩니다. 한도를 높여 다시 시도하세요.

백그라운드 요청이 64K에서 멈추는 이유는 무엇인가요?
Google 네이티브 백그라운드 경로에서 max_output_tokens를 생략하면 서버가 64K에서 멈춥니다. 한도를 명시적으로 설정하세요. 네이티브 장시간 디코딩은 입력을 제외하고 최대 1,048,576까지 지원합니다. AIHubMix는 백그라운드 모드를 문서화하지 않았습니다.

temperature가 적용되나요?
아니요. temperature, top_p, top_k는 무시됩니다. 페널티를 설정하거나 candidate_count를 1보다 큰 값으로 설정하면 대신 400 오류가 반환됩니다.

12월 1일에 Carbon 요금이 두 배가 되나요?
Google 요금은 두 배가 됩니다. 입력은 $2에서 $4로, 출력은 $10에서 $20으로, 캐시 읽기는 $0.10에서 $0.20으로 인상됩니다. AIHubMix는 12월 이후 가격을 공개하지 않았으므로 예산을 확정하기 전에 확인하세요.

Carbon에서 Claude Code나 Codex를 사용할 수 있나요?
확인되지 않았습니다. AIHubMix는 Carbon에 Chat Completions를 문서화했습니다. Claude Code에는 Anthropic Messages가 필요하고 Codex에는 Responses가 필요합니다. 먼저 모델 페이지를 확인하세요.

계속 읽기: Gemini 4 Carbon 시리즈

• 마이그레이션을 진행 중이고 Carbon이 실제로 가격만큼의 가치가 있는지가 남은 질문이라면, 비교 글에서 두 모델에 공통으로 적용되는 출시 기념 요금을 나란히 살펴볼 수 있습니다.
  Gemini 4 Carbon vs Argon: 같은 가격, Carbon은 언제 더 나은 선택일까요?
• 엔드포인트를 마이그레이션하는 대신 코딩 에이전트를 선택하고 있다면, 상세 비교에서 도구 사용과 작업당 비용을 다룹니다.
  Gemini 4 Carbon vs Fable 5.2: 에이전틱 코딩에는 어느 쪽이 적합할까요?

출처

• AIHubMix의 Gemini 4 Carbon
• Gemini 4 Carbon의 새로운 기능 — Google AI Studio
• Gemini 4 Carbon 가이드 — Google Cloud
• 장시간 디코딩 — Google AI Studio
• Gemini API 요금 — Google AI Studio