Gemini 4 Carbon API 연결부터 첫 응답 확인까지

정확한 모델 ID인 gemini-4-carbon과 Gemini API 유료 프로젝트를 사용하세요. 새로운 연동은 Google이 권장하는 Interactions API로 시작할 수 있습니다. 상호작용이 완료되고 쓸 수 있는 텍스트까지 받아야 첫 호출이 성공한 것입니다. HTTP 200만으로는 충분하지 않습니다.

Carbon은 2026년 11월 10일 유료 API 개발자에게 공개됐습니다. 그보다 앞선 제한적 접근 공지만으로는 현재 조건을 설명할 수 없습니다. 이 글은 2026년 11월 13일 공식 문서를 확인했으며, 프로젝트와 키를 고르는 단계부터 검사할 수 있는 응답 파일을 저장하는 단계까지 다룹니다.

예제는 Ofox 엔드포인트가 아닌 Google 네이티브 API를 사용합니다. 문서에 명시된 요청 형식을 확인하고 합성 데이터로 응답 파서를 테스트했지만, 이 글을 위해 유료 Carbon 요청을 실행하지는 않았습니다. 예제 프롬프트는 독자가 실행할 확인 작업이지 모델 성능 측정 결과가 아닙니다. 모델 선택이 먼저라면 Carbon·Hydrogen·Argon 비교를 참고하세요.

1. 키가 올바른 유료 프로젝트에 속하는지 확인하기

Gemini API 이용 조건을 충족하는 Google 계정, AI Studio에서 접근 가능한 Google Cloud 프로젝트, 그 프로젝트의 API 키, 활성화된 API 결제가 필요합니다. 이 네 가지를 따로 확인하세요. Gemini 앱이나 Google AI Ultra 구독만으로 애플리케이션이 사용하는 프로젝트의 API 결제가 설정되지는 않습니다.

1. Google AI Studio를 열고 사용할 프로젝트를 선택합니다. 기존 Cloud 프로젝트가 있다면 필요에 따라 AI Studio로 가져옵니다. 키 생성 버튼을 보이게 하려는 이유만으로 관계없는 프로젝트를 만들지 마세요.
2. 해당 프로젝트의 API 키 관리에서 키를 생성하거나 선택합니다. 배포 기록에는 비밀 키 대신 프로젝트 이름 또는 ID를 남기고, 터미널이나 서버가 바로 그 프로젝트의 키를 읽는지 확인합니다.
3. AI Studio 프로젝트 결제 설정에서 같은 프로젝트의 유료 설정을 마칩니다. 계정에 따라 Prepay, Prepay/Postpay 선택 또는 전환 기간의 Postpay 방식이 적용될 수 있습니다. Prepay는 최소 미화 5달러 또는 현지 통화 상당액을 요구할 수 있습니다. 카드 등록만으로 요청 비용이 충당된다고 판단하지 말고 실제 계정의 결제 상태를 따르세요.
4. 결제가 활성화됐고 필요한 선불 잔액이 있는지 확인합니다. 요청 전에 프로젝트 할당량과 지역 이용 조건도 살펴보세요. 유료 프로젝트에도 제한은 있습니다.

출처는 Google의 API 키 안내와 결제 안내입니다. 프로젝트를 가져오거나 키를 만들 수 없다면 관리자에게 해당 작업에 필요한 권한을 확인해 달라고 요청하세요. 키를 공개하거나 지나치게 넓은 권한을 부여해서 해결할 문제는 아닙니다.

2026년 11월 13일 촬영한 공식 영문 페이지입니다. 개발자 공개 사실을 보여 주며, 독자 계정의 결제 상태나 API 호출 성공을 입증하는 화면은 아닙니다. 공지 원문.

기존 키의 실패 원인이 오타만은 아닙니다

AI Studio에서 새로 만드는 키는 현재 authorization key가 기본입니다. 현행 문서에 따르면 제한이 없는 standard key는 거부되지만, 명시적으로 제한을 설정한 standard key는 계속 사용할 수 있습니다. 오래된 키를 모두 무효라고 보지 말고 유형과 제한을 확인하세요.

키는 서버 환경 변수나 비밀 관리 서비스에 보관합니다. 로컬에서는 GEMINI_API_KEY를 설정하되 값을 저장소에 커밋하지 마세요. 스크린샷, 문의 글, 브라우저 JavaScript에도 넣지 않습니다. 예제에서 GEMINI_API_KEY를 명시적으로 읽는 이유는 SDK 자동 감지 시 GOOGLE_API_KEY가 우선하기 때문입니다. 남아 있는 옛 변수가 모르게 다른 프로젝트를 선택할 수 있습니다.

비밀 값을 출력하지 않고 변수 존재 여부만 확인할 수 있습니다.

python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'

True는 값이 있다는 뜻일 뿐입니다. 키 유효성, 프로젝트, 결제 상태를 검증하지 않습니다. 다음 요청에서 그 다음 단계의 증거를 확인합니다.

2. Python으로 한도를 정한 첫 요청 보내기

다른 앱에 설치된 오래된 SDK의 영향을 받지 않도록 별도 환경을 만듭니다.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade 'google-genai>=2.34.0'
python -m pip show google-genai

Windows PowerShell에서는 .venv\Scripts\Activate.ps1로 활성화합니다. 패키지는 google-genai, 가져오는 구문은 from google import genai입니다. 예전 google-generativeai 패키지로 바꾸지 마세요. 기본 Interactions 지원과 포그라운드 자동 이어가기의 최소 버전은 다릅니다. 위 버전 하한은 현재 Python 자동 이어가기를 포함하지만, 아래 짧은 요청은 의도적으로 한 번의 응답 범위로 제한합니다. Interactions 문서와 긴 출력 안내를 참고하세요.

다음을 carbon_first_call.py로 저장합니다.

import json
import os
from pathlib import Path
from google import genai

key = os.environ.get("GEMINI_API_KEY")
if not key:
    raise SystemExit("Set GEMINI_API_KEY for the intended paid project.")

client = genai.Client(api_key=key)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Return exactly three checklist items for reviewing an API integration.",
    store=False,
    generation_config={
        "thinking_level": "low",
        "max_output_tokens": 32768,
    },
)

payload = interaction.model_dump(mode="json")
Path("carbon-response.json").write_text(
    json.dumps(payload, indent=2), encoding="utf-8"
)
text = interaction.output_text or ""
print("Interaction:", interaction.id)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
if interaction.status != "completed" or not text.strip():
    raise SystemExit("No completed text result; inspect carbon-response.json.")
print(text)

python carbon_first_call.py를 실행합니다. 유료 요청이 전송됩니다. 먼저 한 가지 방식만 실행하고, Python과 REST 예제를 자동으로 연달아 돌려 중복 테스트하지 마세요. 32,768토큰은 추론과 사용자에게 보이는 출력의 합계 상한입니다. 청구액 예측도, 그만큼의 글을 생성하라는 요구도 아닙니다. 짧은 프롬프트와 low 설정은 복잡한 연구가 아니라 연결 확인에 초점을 맞춥니다.

성공하면 상호작용 ID, completed, 사용량, 의미 있는 체크 항목 세 개가 표시됩니다. 상태뿐 아니라 답변도 읽으세요. 완료된 응답도 형식이나 내용 조건을 어길 수 있습니다. 진단을 위해 JSON을 보관하되, 나중에 고객 데이터를 넣으면 응답 파일 역시 민감한 업무 정보가 들어 있을 수 있는 자료로 취급합니다.

이 예제는 단발성 요청이므로 store=False입니다. 나중에 조회하거나 서버에서 대화를 이어가기 위한 해당 상호작용 저장을 끄는 설정이지, 모든 제공업체의 로그 정책을 포괄적으로 보장하는 설명은 아닙니다. 기본값은 store=true입니다. 백그라운드 작업이나 previous_interaction_id에 의존하는 예제에 그대로 복사하지 마세요.

3. REST로 호출하고 올바른 필드에서 텍스트 읽기

REST는 클라이언트가 실제로 보내는 내용을 확인하기 좋습니다. curl과 파서 실행용 Python 3가 필요합니다. 다음 본문을 carbon-request.json으로 저장합니다.

{
  "model": "gemini-4-carbon",
  "input": "Return exactly three checklist items for reviewing an API integration.",
  "store": false,
  "generation_config": {
    "thinking_level": "low",
    "max_output_tokens": 32768
  }
}

Interactions 엔드포인트로 전송합니다.

curl --silent --show-error --fail-with-body --max-time 900 \
  'https://generativelanguage.googleapis.com/v1beta/interactions' \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @carbon-request.json \
  --output carbon-response.json

서버 오류 본문이 돌아와도 파일에 저장해 검사할 수 있습니다. curl 종료 코드가 0이 아니라면 전송이나 HTTP 요청 문제를 확인해야 하며, 답변을 받은 것처럼 계속 진행하면 안 됩니다. 900초는 명시적인 클라이언트 제한 시간이지 Carbon이 항상 15분 걸린다는 뜻은 아닙니다. 클라이언트 시간 초과만으로 서버 처리가 멈췄는지도 알 수 없습니다. 상황을 확인하지 않고 과금될 수 있는 작업을 즉시 다시 보내지 마세요.

output_text는 SDK의 편의 속성으로, REST 응답 필드가 아닙니다. REST 텍스트는 steps 안의 model_output 항목에 있는 text 콘텐츠에서 읽습니다. GenerateContent의 candidates나 오래된 예제의 outputs를 읽는 파서는 정상 응답을 빈 결과로 오해할 수 있습니다.

응답 파일 옆에 다음을 inspect_carbon.py로 저장합니다.

import json
import sys
from pathlib import Path


def extract_text(payload):
    return "".join(
        part.get("text", "")
        for step in payload.get("steps", [])
        if step.get("type") == "model_output"
        for part in step.get("content", [])
        if part.get("type") == "text"
    )


def inspect(path):
    payload = json.loads(Path(path).read_text(encoding="utf-8"))
    if "error" in payload:
        raise SystemExit("API error: " + json.dumps(payload["error"]))
    text = extract_text(payload)
    print("Interaction:", payload.get("id"))
    print("Status:", payload.get("status"))
    print("Usage:", json.dumps(payload.get("usage")))
    if payload.get("status") != "completed" or not text.strip():
        raise SystemExit("No completed text result; inspect the saved response.")
    print(text)


if __name__ == "__main__":
    inspect(sys.argv[1] if len(sys.argv) > 1 else "carbon-response.json")

python3 inspect_carbon.py carbon-response.json을 실행합니다. 첫 step이 최종 답변이라고 가정하지 않고 모든 텍스트 부분을 합칩니다. 일부만 완료됐거나 추가 동작이 필요한 상호작용은 의도적으로 성공 처리하지 않습니다. 모니터링에도 활용할 수 있지만 실패를 무제한 재시도 반복문에 연결하지 마세요.

파서는 완료, 빈 결과, 오류, 여러 step을 포함한 합성 응답으로 로컬 테스트했습니다. 추출과 실패 처리 검증일 뿐, Google 실제 API의 인증, 가용성, 지연 시간, 품질을 입증하지 않습니다.

4. 실제 작업을 붙이기 전에 설정 이해하기

첫 요청에는 도구, 큰 파일, 장시간 에이전트 반복을 넣지 않았습니다. 연결이 확인되면 하나씩 추가하세요. Carbon 개발자 안내에서 확인할 수 있는 경계는 다음과 같습니다.

출력 상한이 작은 앱을 옮길 때 Google은 추론·출력에 최소 32,768토큰을 허용하도록 권장합니다. 예산 배분이지 매번 최대치를 소비한다는 뜻은 아닙니다. 적절하면 추론 수준을 낮추고, 답변 길이로 비용을 추측하지 말고 사용량을 보세요. 가격 조건과 다시 계산할 수 있는 비교는 Gemini 4 모델 선택 안내에 있습니다.

첫 호출을 장시간 작업으로 확장한다면

다른 코드는 그대로 두고 max_output_tokens만 키우지 마세요. 긴 출력 문서는 포그라운드 이어가기, 스트리밍, 백그라운드 실행을 구분합니다. 최신 SDK는 포그라운드 여러 단계를 합칠 수 있지만, 직접 만든 REST 클라이언트는 requires_continuation을 처리하고 필요한 이어가기 정보를 전달해야 합니다.

백그라운드 작업에서는 저장을 켜고 상호작용 ID를 보관하며, 대기 시간이 제한된 폴링을 사용합니다. queued, in_progress는 대기 중이고, completed는 결과를 검사할 단계입니다. incomplete, failed, cancelled는 서로 다른 종료 상태입니다. requires_action은 도구 실행이 필요하다는 뜻이지 최종 답변이 준비됐다는 뜻이 아닙니다. 예산 증가나 background=true가 출력 길이를 보장하지도 않습니다. 이 첫 호출 예제는 별도의 장시간 작업 제어기를 구현하지 않습니다.

서버 측 대화 기록에서 previous_interaction_id는 이전 대화를 전달하지만 tools, system_instruction, generation_config는 상속하지 않습니다. 다음 턴에도 필요하면 다시 보내세요. Interactions는 기본적으로 응답을 저장하며, Google 유료 등급 기본 보관 기간은 55일이고 더 짧은 기간도 설정할 수 있습니다. 복사한 코드에 따라 무심코 결정하지 말고 저장 방식을 선택하세요.

5. 실패한 단계부터 순서대로 진단하기

구조화된 오류를 읽고 엔드포인트, 정확한 모델 ID, 프로젝트 식별자, SDK 버전, 시간을 기록합니다. 비밀 키는 제외합니다. 프롬프트나 예산을 바꾸기 전에 가장 먼저 실패한 부분부터 고칩니다.

Google의 문제 해결 안내에서 오류 분류를 확인할 수 있습니다. Argon API 오류 진단도 경로·할당량·응답 문제를 나누는 데 유용하지만, Argon 고유 정보는 Carbon과 구분해야 합니다. 도구를 추가한 뒤 서명 검증 오류가 생긴다면 기록을 무작정 삭제하지 말고 missing thought signature 진단으로 해당 프로토콜 문제를 확인하세요.

기존 Gemini 클라이언트 옮기기

정상 작동하는 기준 버전을 남기고 하나씩 변경합니다. Google의 네이티브 GenerateContent API는 계속 지원됩니다. 새 프로젝트에 Interactions를 권장한다고 해서 작동 중인 모든 클라이언트를 당장 바꿔야 하는 것은 아닙니다.

옮길 때는 요청 형식과 응답 파서를 함께 수정하세요. 모델만 gemini-4-carbon으로 바꾸고 여전히 candidates를 읽는 코드는 이전이 끝난 것이 아닙니다. 추론 설정, 명시적 캐시 참조, 오래된 샘플링 가정을 확인하고 시간 제한과 출력 한도도 검토합니다. JavaScript Interactions의 generation_config, thinking_level, max_output_tokens는 snake_case입니다. GenerateContent의 설정 대소문자를 그대로 가져오지 마세요.

도구와 고객 파일을 다시 연결하기 전에 동일한 무해한 확인 프롬프트를 실행합니다. 그다음 합격 기준이 알려진 대표 작업 하나를 검사하세요. 첫 호출 성공은 연동 경로를 검증할 뿐, 여러 단계로 실행되는 운영 에이전트의 신뢰성을 보장하지 않습니다.

이 예제를 Ofox로 호출할 수 있나요?

이 글의 발행자는 Ofox이지만 예제는 Google 네이티브 인증과 엔드포인트를 사용합니다. 2026년 11월 13일 확인한 공개 catalog 스냅샷에는 Carbon이 없었습니다. 특정 날짜의 관찰이며, 모든 계정이나 앞으로의 경로에서 지원하지 않는다는 증거는 아닙니다. Ofox Carbon 호출을 검증하지 않았고, Base URL만 바꾸면 작동한다고 주장하지 않습니다.

Ofox 연동에서는 정확한 모델의 현재 제공 여부와 지원 프로토콜을 먼저 확인하세요. 이후 Ofox Gemini API 문서에 따라 해당 경로의 엔드포인트, 인증, 요청 형식을 설정합니다. Ofox 키와 Google 키는 따로 관리합니다. Gemini 호환 경로가 있다는 사실만으로 Google Interactions 엔드포인트나 Carbon 모든 기능의 지원을 알 수는 없습니다.

Ofox 경로의 오류는 Ofox 오류 처리 안내와 실제 응답을 확인하세요. Google 결제 계정, Ofox 잔액, 앱 구독은 서로 다릅니다. 한 곳의 잔액으로 다른 곳의 요청이 결제되지는 않습니다.

첫 호출을 확인한 뒤 남길 기록

설정을 마쳤다고 판단하기 전에 비밀을 제외한 다음 증거를 보관하세요.

• 정확한 모델, 엔드포인트, SDK 버전, 프로젝트 식별자.
• 상호작용 ID, 상태, 사용량이 포함된 응답 파일.
• 세 항목이라는 요구를 충족한 추출 텍스트.
• 해당 요청의 추론 수준, 출력 예산, 저장 설정.
• 발생한 오류와 실제로 해결한 구체적 수정.

이제 접근 권한, 프로토콜, 출력 문제를 구분할 기준이 생겼습니다. 도구나 큰 프롬프트를 추가했을 때 기준 호출은 통과하고 새 작업만 실패한다면 변경한 부분을 조사하세요. 매번 키를 다시 만들고 결제 프로젝트를 옮기거나 에이전트 전체를 반복 실행할 필요는 없습니다.