> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 4 Carbon 텍스트 생성

> Google의 가장 강력한 추론 모델인 Gemini 4 Carbon이 APIYI에서 Gemini 네이티브 및 OpenAI 호환 엔드포인트로 제공되며, 기간 한정 $2/$10 요율, 1M 통합 윈도우, 세 가지 사고 수준을 지원합니다. 동시 실행 수가 제한된 테스트 결과와 공급자 측 Flash-Lite 전환을 위한 지침이 포함되어 있습니다.

Gemini 4 Carbon (`gemini-4-carbon`)은 Google의 가장 강력한 추론 모델입니다. 2026년 10월 28일에 발표되었고 11월 10일에 모든 유료 개발자와 기업에 공개되었으며, 현재 APIYI에서 사용할 수 있습니다. 일상적인 채팅을 위한 모델이 아니라 **장기 에이전트 코딩, 고밀도 멀티모달 지식 작업, 과학적 추론 및 사이버 보안 방어**를 목표로 합니다. 동일한 모델이 대규모 코드베이스에서 빌드 및 검증 루프를 실행하거나, PDF, 스프레드시트 및 프레젠테이션 자료 전반에서 근거를 바탕으로 답변을 종합할 수 있습니다.

APIYI는 `default` 및 `svip` 그룹에서 **Gemini 네이티브** 및 **OpenAI 호환** 엔드포인트를 모두 제공합니다. 출시 전에 두 엔드포인트, 스트리밍, 함수 호출, 구조화된 출력, 이미지 입력, 사고 수준 및 약 199K token 규모의 건초 더미에서 바늘 찾기 테스트를 포함한 낮은 동시 실행 수 테스트를 수행했습니다. 결과와 현재 제한 사항은 이 페이지에 문서화되어 있습니다.

> [!NOTE]
>
> **가격**: 1M token당 입력 \$2 / 출력 \$10이며, Google의 기간 한정 요율은 **2026년 11월 30일까지** 적용됩니다. **12월 1일부터는 표준 요율인 \$4 / \$20이 적용**되며 APIYI도 이를 따릅니다. 캐시된 입력은 1M token당 \$0.10입니다.

> [!WARNING]
>
> **출시 시 유의할 두 가지 사항**:
>
> * Google은 요청별로 응답 모델을 전환할 수 있는 권한을 보유하며, 리소스를 조정한 후에는 이 문제가 재현되지 않았습니다. `modelVersion`이 `gemini-4-carbon`이 아닌 경우 이를 기록하고 재시도하십시오. 이는 **요청이 정책을 위반했다는 의미가 아닙니다**. 자세한 내용은 아래의 “제공자 측 모델 전환”을 참조하십시오.
> * `maxOutputTokens`이 이제 적용되지만 **사고 token이 포함됩니다**. 너무 낮게 설정하면(테스트에서는 300으로 설정했을 때 발생) 모델이 `MAX_TOKENS`으로 사고를 완료하고 답변 없이 종료할 수 있으므로, 어려운 작업을 위해 여유를 두십시오.

## 주요 내용

> [card] 지능 평가 1위
>
> Google은 Artificial Analysis Intelligence Index v5에서 59점을 받아 1위를 기록했다고 보고했습니다. 또한 CursorBench 4.0, Perplexity WANDR, Zapier AutomationBench에서도 1위를 기록했으며, Google은 차상위 외부 모델보다 작업당 비용이 2배 이상 낮다고 주장합니다.

> [card] 사이버 보안 분야의 최첨단 성능
>
> 취약점 탐지에서 SEC-bench Pro 88.2%, 익스플로잇 가능성 검증에서 ExploitGym 54.8%, 근본 원인 패치에서 CWE-bench 71.0%를 기록했습니다. 모두 Google이 보고한 수치이며, 가드레일 없이 평가되었습니다.

> [card] 공식 1M 통합 윈도우
>
> 입력, 추론 및 출력이 1,048,576 token을 공유하며, 단일 스트리밍 세그먼트에서 최대 65,536 token을 생성할 수 있고 그 이후에는 장문 디코드 연속 생성을 지원합니다. **199K-token 문서가 당사의 니들 테스트를 통과했지만, 실제로 사용하기 전에 소규모 샘플로 500K\~1M을 검증해야 합니다.**

> [card] 두 개의 엔드포인트, 완전한 도구 체인
>
> 두 엔드포인트 모두에서 왕복 호출을 포함한 함수 호출, JSON Schema, 이미지 입력 및 스트리밍이 통과되었습니다. Google은 코드 실행, URL 컨텍스트, Computer Use, Office / PDF 파일 입력도 지원합니다.

## 모델 정보

| 매개변수 | 값 |
| - | - |
| **모델 이름** | `gemini-4-carbon` |
| **입력 모달리티** | 텍스트, 이미지, 동영상, 오디오(공식 지원; 테스트에서는 텍스트와 이미지 지원 확인) |
| **출력 모달리티** | 텍스트 |
| **컨텍스트 윈도우** | 공식 1,048,576 token(입력, 추론 및 출력에서 공유); 199K token 검증 완료 |
| **최대 출력** | 긴 디코딩 사용 시 공식 1,048,576 token; 스트리밍 세그먼트당 65,536, 비스트리밍 32,768 |
| **추론 수준** | 기본값 `medium`; `low` / `medium` / `high` 지원; `thinkingBudget` 및 `minimal`은 **지원되지 않음** |
| **지식 기준일** | 2026년 3월 |
| **그룹** | `default`, `svip` |
| **엔드포인트** | `POST /v1beta/models/gemini-4-carbon:generateContent`(네이티브), `POST /v1/chat/completions`(OpenAI 호환) |
| **스트리밍** | ✅ 두 엔드포인트 모두 |
| **캐싱** | 암시적 캐싱만 지원(공식, 최소 4,096 token); 캐시된 입력은 1M token당 \$0.10 |

## 공식 벤치마크

아래의 모든 수치는 **Google이 게시한 것**이며 APIYI가 독립적으로 재현한 결과가 아닙니다.

| 벤치마크 | 측정 대상 | Gemini 4 Carbon |
| - | - | - |
| Artificial Analysis Intelligence Index v5 | 일반 지능 | 59 (#1) |
| SEC-bench Pro | 실제 취약점 탐지 | 88.2% |
| ExploitGym | 악용 가능성 검증 | 54.8% |
| CWE-bench | 근본 원인 패치 | 71.0% |
| WebDev Arena | 웹 개발 | #4, 1768 (+89 Elo) |
| CursorBench 4.0 | 실제 코딩 작업 | #1 |
| Perplexity WANDR | 광범위하고 심층적인 리서치 | #1 |
| Zapier AutomationBench | 엔드투엔드 비즈니스 워크플로 | #1, 작업당 비용 2배 이상 절감 |
| Artificial Analysis MKA | 멀티모달 지식 에이전트 | #2, 작업당 비용 6배 이상 절감 |

타사인 Artificial Analysis는 Carbon의 AA-Omniscience 환각률을 별도로 \*\*11%\*\*로 측정했습니다(Argon: 약 4%). 또한 Carbon을 매우 장황한 모델로 평가했으며, 전체 인덱스 실행에 약 2억 개의 출력 token을 사용했습니다(중앙값은 6,400만 개). 사실 확인이 필요한 작업에서는 출처를 요청하고 검증하십시오.

## 추론 및 매개변수

| 설정 | 동작 |
| - | - |
| `thinkingConfig` 없음 | 기본값은 `medium`입니다 |
| `thinkingConfig.thinkingLevel: low` | 추론 수준이 가장 낮고 첫 token이 가장 빠릅니다. 간단한 작업 및 작성에 적합합니다 |
| `thinkingConfig.thinkingLevel: medium` | 대부분의 코드 및 에이전트 작업에 대한 Google의 권장 설정입니다 |
| `thinkingConfig.thinkingLevel: high` | 추론 수준이 가장 높고 첫 token이 가장 느립니다. 어려운 수학, 과학 및 복잡한 코드에 적합합니다 |
| `thinkingConfig.thinkingBudget` | Google에서 지원하지 않으며 400을 반환해야 합니다. 테스트에서 값이 0으로 허용된 경우가 있었지만, **이에 의존하지 마십시오** |
| `thinkingConfig.thinkingLevel: minimal` | 400, `Thinking level MINIMAL is not supported` |
| `temperature` / `topP` / `topK` | Google에서 각각 1.0 / 0.95 / 64로 고정하며, 사용자 지정 값은 무시됩니다 |
| `maxOutputTokens` | 추론 및 출력에 대한 공식 상한입니다. **현재 적용되지만**, 값이 너무 작으면 답변을 생성하지 못할 수 있습니다 |
| `stopSequences` | ✅ 적용됩니다(테스트에서 `END`에서 중단됨) |

`maxOutputTokens`에는 추론 token이 포함되므로 Google은 충분한 여유를 둘 것을 권장합니다. 테스트에서는 50 / 100 / 300 모두 추론 중에 한도에 도달하여 텍스트가 거의 또는 전혀 없는 `finishReason=MAX_TOKENS`를 반환했습니다. 완전한 답변을 얻으려면 몇 천 정도로 설정하십시오. 이제 이 매개변수는 APIYI를 통해 그대로 전달됩니다.

## 공식 1M, 199K 검증 완료

공식 모델 카드는 입력, 추론 및 출력에 공유되는 **1,048,576 token**을 제공하며, 스트리밍 세그먼트당 최대 65,536 token과 그 이상을 지원하는 장문 디코드 연속 처리를 명시합니다. 리소스 조정 후 다시 테스트한 결과는 다음과 같습니다.

| 입력 크기 | 보고된 `promptTokenCount` | 끝부분의 니들 발견 여부 |
| - | - | - |
| 616,090자(약 199K token) | 199,277 | ✅ |

이전의 약 128K 제한 및 무음 잘림은 재현되지 **않았습니다**. 이번 라운드에서는 500K / 1M 범위를 테스트하지 않았으므로, 매우 긴 문서를 보내기 전에 소규모 샘플로 검증하시기 바랍니다.

## 빠른 시작

### Gemini 네이티브 엔드포인트

```bash theme={null}
curl https://api.apiyi.com/v1beta/models/gemini-4-carbon:generateContent \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Prove that the square root of 2 is irrational."}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }'
```

### OpenAI 호환 엔드포인트

```bash theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [{"role": "user", "content": "Explain tidal locking."}],
    "max_tokens": 1024
  }'
```

> 참고: 이제 `max_tokens`가 적용되지만, thinking tokens도 여기에 포함됩니다. 값을 너무 낮게 설정하면 답변이 없는 `MAX_TOKENS` 응답이 발생하므로, 어려운 작업을 위해 여유를 두십시오.

## 과금 및 캐싱

| 항목 | 100만 tokens당 가격 |
| - | - |
| 입력 | \$2 (2026년 12월 1일부터 \$4) |
| 출력(추론 포함) | \$10 (2026년 12월 1일부터 \$20) |
| 캐시된 입력 | \$0.10 (입력 요금에서 95% 할인) |

* 기간 한정 요율은 **2026년 11월 30일까지** 적용됩니다. 12월 1일부터는 Google의 표준 가격이 적용되며 APIYI도 이를 따릅니다.
* 암시적 캐싱만 지원되며, 최소 4,096 tokens가 필요합니다. 명시적 `cachedContents`은 지원되지 않습니다.
* Thinking tokens는 출력으로 과금되므로 `high`은 `low`보다 비용이 눈에 띄게 높습니다.

## 제공업체 측 모델 전환: 양상과 대응 방법

**발생하는 현상**: `gemini-4-carbon`을 호출하면 네이티브 응답의 `modelVersion`은 거의 항상 `gemini-4-carbon`여야 합니다. 이전에는 일부 응답에서 `3.1-flash-lite-05-2026`이 보고되었으며, 이 경우 지연 시간이 훨씬 짧고 사고 token이 매우 적었습니다. 스트리밍에서는 동일한 `responseId`에 여러 청크에 걸쳐 두 버전이 모두 포함될 수 있었습니다. **리소스 조정 이후에는 이 현상이 재현되지 않았습니다.**

**해석 방법**: 이는 Google이 요청별로 응답 모델을 전환하고 있다는 의미입니다. Google의 사용 정책에서는 요청별 응답 모델 변경을 허용하며, Google 개발자 포럼에도 `gemini-3.1-pro-preview`이 `3.1-flash-lite-preview-03-2026`으로 제공되었다는 매우 유사한 보고가 있습니다. APIYI에서 확인한 스냅샷은 `05-2026`이었습니다. **요청이 정책을 위반했다는 의미가 아니며**, 계정에 불이익이 발생했다는 의미도 아닙니다. 정확한 트리거는 외부에서 확인할 수 없으며, 라우팅 또는 위험 제어 정책, 버전이나 과금 메타데이터의 이상일 수 있습니다. 현재는 안정적이지만 Google이 이러한 변경을 수행할 가능성은 여전히 있습니다.

**영향**:

* 간단한 작업은 대체로 동일하게 보이지만, Flash-Lite로 제공될 경우 어려운 작업, 장기 실행 에이전트 및 심층 추론 작업의 품질이 저하될 수 있습니다.
* 다시 발생하면 지연 시간이 비정상적으로 짧고 사고 token이 드문 양상으로 나타납니다. **이를 Carbon 네이티브 성능으로 간주해서는 안 됩니다.**

**권장 사항**:

1. 중요한 작업에서는 네이티브 응답의 `modelVersion`을 기록하십시오(OpenAI 호환 엔드포인트에서는 이를 반환하지 않음). `3.1-flash-lite`으로 보고되면 재시도할지 결정하십시오.
2. 일관성이 중요한 작업에는 검증 절차를 추가하십시오. 출처를 요청하거나, 단위 테스트를 실행하거나, 다른 모델과 교차 확인하십시오.
3. `thinkingLevel: high`과 명시적인 단계 제약을 사용하여 작업의 복원력을 높이십시오.
4. SLA에 “항상 Carbon으로 제공됨”을 포함하지 마십시오.

## 모델 선택

| 시나리오 | 권장 사항 |
| - | - |
| 어려운 문제, 장기적인 코딩, 과학적 추론, 보안 감사 | 충분한 출력 예산과 함께 Carbon 및 `thinkingLevel: high` 사용 |
| 일상적인 코딩, 지식 작업, 대화형 작업 | Argon이 더 빠르고 저렴합니다. Carbon의 추가 추론이 항상 비용 대비 효과적인 것은 아닙니다 |
| 높은 동시 실행 수, 짧은 지연 시간, 비용 민감형 작업 | Flash 시리즈 또는 Flash-Lite를 사용합니다. Carbon은 적합하지 않습니다 |
| 매우 긴 문서(>200K token) | 이번 라운드에서는 199K만 검증되었습니다. 먼저 문서를 여러 부분으로 나누거나 소규모 샘플로 검증합니다 |

> [!NOTE]
>
> 모델 과금은 공식 사이트를 기준으로 하며 변경될 수 있습니다. 위 표는 참고용일 뿐입니다. 상단 탐색 메뉴의 **모델 과금** 탭이 기준입니다: [모델 과금](https://docs.apiyi.com/ko/models/index.md).

## 관련 문서

* [Gemini 4 Carbon 출시 안내](https://docs.apiyi.com/en/news/gemini-4-carbon-launch.md)
* [Gemini 4 Carbon 모델 세부 정보](https://docs.apiyi.com/ko/models/gemini-4-carbon.md)
* [Gemini 네이티브 엔드포인트](https://docs.apiyi.com/ko/api-capabilities/gemini/native.md)
* [Gemini 4 Argon 개요](https://docs.apiyi.com/ko/api-capabilities/gemini-4-argon/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.