curl --request POST \
--url https://direct.evolink.ai/v1beta/models/{model}:generateContent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "오늘 상하이 날씨는 어때요?"
}
]
}
],
"tools": [
{
"googleSearch": {}
}
]
}
'{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "Hello! I'm pleased to introduce myself.\n\nI'm a large language model, trained and developed by Google...",
"thought": true,
"thoughtSignature": "<Signature_A>"
}
]
},
"finishReason": "STOP",
"continuationToken": "<string>",
"index": 0,
"safetyRatings": [
{}
]
}
],
"promptFeedback": {
"safetyRatings": [
{}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 611,
"totalTokenCount": 2422,
"thoughtsTokenCount": 1807,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"cachedContentTokenCount": 0
},
"modelVersion": "gemini-3.6-flash",
"responseId": "l-LoaPu0BPmo1dkP6ZPHiQc"
}{
"error": {
"code": 400,
"message": "잘못된 요청 매개변수",
"type": "invalid_request_error"
}
}{
"error": {
"code": 401,
"message": "Invalid or expired token",
"type": "authentication_error"
}
}{
"error": {
"code": 402,
"message": "할당량 부족",
"type": "insufficient_quota_error",
"fallback_suggestion": "https://evolink.ai/dashboard/credits"
}
}{
"error": {
"code": 403,
"message": "Access denied for this model",
"type": "permission_error"
}
}{
"error": {
"code": 404,
"message": "Model not found",
"type": "not_found_error"
}
}{
"error": {
"code": 413,
"message": "요청 본문이 너무 큼",
"type": "request_too_large_error",
"fallback_suggestion": "reduce file size"
}
}{
"error": {
"code": 429,
"message": "랜덤 시드, 범위 `[0, 2147483647]`, 동일한 시드 값을 사용하면 생성 결과를 일관되게 유지할 수 있습니다",
"type": "rate_limit_error",
"fallback_suggestion": "retry after 60 seconds"
}
}{
"error": {
"code": 500,
"message": "내부 서버 오류",
"type": "internal_server_error",
"fallback_suggestion": "try again later"
}
}{
"error": {
"code": 502,
"message": "Upstream AI service unavailable",
"type": "upstream_error",
"fallback_suggestion": "try again later"
}
}{
"error": {
"code": 503,
"message": "서비스 일시적으로 사용 불가",
"type": "service_unavailable_error",
"fallback_suggestion": "retry after 30 seconds"
}
}Gemini 전체 모델 인터페이스 - Native API 형식
경로의 {model}을 통해 호출할 Gemini 텍스트 모델을 선택합니다(전체 선택 가능한 값은 model 파라미터의 대조표 참조).
- Google Native API 형식을 사용하여 대화 내용을 동기적으로 반환
- 일반 텍스트 / 멀티모달 입력: 텍스트 + 이미지 / 오디오 / 비디오 혼합 입력
- 스트리밍: 경로의
generateContent를streamGenerateContent로 대체(?alt=sse를 추가하여 SSE 획득 가능)
모델 사양 및 차이점
- 3.8 동작: 3.7보다 소프트웨어 엔지니어링, 에이전트, 다단계 추론 및 멀티모달 정확도가 향상되었습니다. 특히
high에서는 추론 / 출력 Token을 더 많이 사용할 수 있습니다. 지연 시간에 민감한 작업에는low, 일반 작업에는 기본값인medium, 복잡한 코드, 긴 동영상 또는 다단계 추론에는high를 권장합니다. - Gemini 4 Argon 동작: 사고는
thinkingConfig.thinkingLevel로만 제어하며low/medium/high를 지원합니다. 생략하면 모델이 사고량을 자동으로 결정합니다.minimal은 지원하지 않습니다(전달하면 400 반환, 대신low사용).thinkingBudget도 지원하지 않습니다(전달하면 400 반환).temperature/topP가 유효 범위를 벗어나면 400을 반환합니다. 여러 턴의 함수 호출에서는 이전 턴에서 반환된thoughtSignature를 변경 없이 다시 전달해야 하며, 그렇지 않으면 400을 반환합니다. 입력은 텍스트 / 이미지 / 오디오 / 동영상 / PDF를 지원합니다. - 샘플링 파라미터
temperature/topP/topK: Gemini 3.x 전 시리즈 동일하며, 사용자 지정 값은 출력에 영향을 주지 않습니다.topK는 무시되어 적용되지 않고,temperature/topP는 유효 범위를 벗어나면 400을 반환합니다. - 사고 제어: Gemini 3.x / 4 시리즈는
thinkingConfig.thinkingLevel(각 모델이 지원하는 레벨과 기본값은thinkingLevel파라미터 참조)을 사용하며, Gemini 2.5 시리즈는thinkingConfig.thinkingBudget(정수,0=비활성화)을 사용합니다. 둘은 상호 배타적입니다.gemini-3.8-flash/gemini-3.7-flash와 Pro 계열은minimal을 지원하지 않으며, 전달하면 자동으로low로 다운그레이드됩니다. - 함수 호출: Gemini 3.x의
FunctionResponse는 대응하는FunctionCall과 일치하는id와name을 반드시 함께 반환해야 하며, 그렇지 않으면 오류가 발생합니다. - 마지막 턴 역할: 마지막 메시지의
role은model일 수 없습니다(Gemini 3.5+에서 오류 발생). - Token 상한:
gemini-3.8-flash/gemini-3.7-flash/gemini-3.6-flash/gemini-3.5-flash-lite는 컨텍스트 1,048,576, 최대 출력 65,536입니다.gemini-4-argon은 입력·사고·답변이 1,048,576 컨텍스트를 공유하며, 요청당 상한은 스트리밍 65,536, 비스트리밍 32,768(사고와 답변 합계)입니다. 더 긴 출력에는 이어 생성을 사용하며, 누적 사고와 답변은 입력을 제외한 남은 컨텍스트만 사용할 수 있습니다. 이 페이지의 “긴 출력 이어 생성하기”를 참고하세요. 다른 모델은 각 사양을 따릅니다. - Gemini 2.5 기존 ID: 2026-10-19부터
gemini-2.5-pro/gemini-2.5-flash/gemini-2.5-flash-lite는 각각gemini-3.8-flash/gemini-3.5-flash-lite/gemini-3.1-flash-lite-preview에서 처리되며 해당 요금으로 과금됩니다. 응답에는 새 모델 ID가 표시되고, 파라미터 동작은 새 모델을 따릅니다.thinkingBudget은 레벨로 변환됩니다(thinkingBudget파라미터 참조).
curl --request POST \
--url https://direct.evolink.ai/v1beta/models/{model}:generateContent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "오늘 상하이 날씨는 어때요?"
}
]
}
],
"tools": [
{
"googleSearch": {}
}
]
}
'{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "Hello! I'm pleased to introduce myself.\n\nI'm a large language model, trained and developed by Google...",
"thought": true,
"thoughtSignature": "<Signature_A>"
}
]
},
"finishReason": "STOP",
"continuationToken": "<string>",
"index": 0,
"safetyRatings": [
{}
]
}
],
"promptFeedback": {
"safetyRatings": [
{}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 611,
"totalTokenCount": 2422,
"thoughtsTokenCount": 1807,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"cachedContentTokenCount": 0
},
"modelVersion": "gemini-3.6-flash",
"responseId": "l-LoaPu0BPmo1dkP6ZPHiQc"
}{
"error": {
"code": 400,
"message": "잘못된 요청 매개변수",
"type": "invalid_request_error"
}
}{
"error": {
"code": 401,
"message": "Invalid or expired token",
"type": "authentication_error"
}
}{
"error": {
"code": 402,
"message": "할당량 부족",
"type": "insufficient_quota_error",
"fallback_suggestion": "https://evolink.ai/dashboard/credits"
}
}{
"error": {
"code": 403,
"message": "Access denied for this model",
"type": "permission_error"
}
}{
"error": {
"code": 404,
"message": "Model not found",
"type": "not_found_error"
}
}{
"error": {
"code": 413,
"message": "요청 본문이 너무 큼",
"type": "request_too_large_error",
"fallback_suggestion": "reduce file size"
}
}{
"error": {
"code": 429,
"message": "랜덤 시드, 범위 `[0, 2147483647]`, 동일한 시드 값을 사용하면 생성 결과를 일관되게 유지할 수 있습니다",
"type": "rate_limit_error",
"fallback_suggestion": "retry after 60 seconds"
}
}{
"error": {
"code": 500,
"message": "내부 서버 오류",
"type": "internal_server_error",
"fallback_suggestion": "try again later"
}
}{
"error": {
"code": 502,
"message": "Upstream AI service unavailable",
"type": "upstream_error",
"fallback_suggestion": "try again later"
}
}{
"error": {
"code": 503,
"message": "서비스 일시적으로 사용 불가",
"type": "service_unavailable_error",
"fallback_suggestion": "retry after 30 seconds"
}
}generateContent를 streamGenerateContent로 바꾸세요. 요청 본문은 유지하고 응답을 청크 단위로 받습니다. SSE 형식에는 ?alt=sse를 추가하세요.https://direct.evolink.ai이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. https://api.evolink.ai는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.긴 출력 이어 생성하기(Gemini 4 Argon)
gemini-4-argon은 요청 한 번에 스트리밍으로 최대 65,536토큰, 비스트리밍으로 최대 32,768토큰을 반환하며, 두 상한 모두 사고와 답변 토큰을 포함합니다. 더 긴 출력은 이어 생성 요청으로 나누어 받습니다. 입력·사고·답변은 1,048,576토큰의 컨텍스트를 공유하므로, 누적 사고와 답변에는 입력을 제외한 나머지 공간만 사용할 수 있습니다. 이어 생성은 네이티브 API에서만 지원하며 OpenAI 호환 형식은 지원하지 않습니다.
스트리밍 streamGenerateContent | 비스트리밍 generateContent | |
|---|---|---|
| 요청당 최대 출력 | 65,536 | 32,768 |
| 종료 시 이어 생성 토큰 위치 | 마지막 청크의 candidates[0].continuationToken | candidates[0].continuationToken |
generationConfig.maxOutputTokens를 요청당 상한보다 크게 설정합니다(스트리밍 65,536 초과, 비스트리밍 32,768 초과). 파라미터는 최대 1,048,576까지 받지만 실제 출력은 공유 컨텍스트의 제한을 받습니다. 이 값은 모든 이어 생성 요청에 걸친 사고와 답변의 누적 예산입니다.candidates[0].finishReason이CONTINUATION이면 생성이 끝나지 않은 상태이며, 같은 후보에continuationToken이 반환됩니다.- 원래 요청의
contents,systemInstruction,tools,generationConfig를 그대로 유지하여 다시 보냅니다. 최상위에continuationToken만 추가하고 가장 최근 응답의 토큰을 그대로 넣습니다. finishReason이CONTINUATION일 때만 3단계를 반복하고 다른 종료 사유에서는 멈춥니다.STOP은 정상 완료,MAX_TOKENS는 누적 예산 소진을 뜻합니다. 각 응답에는 새로 생성된 내용만 있으므로 순서대로 연결합니다.
- 이미 생성된 내용을
contents에 추가하거나 “계속해” 같은 새 프롬프트를 보내지 마세요. - 한 요청이 전부 사고에 사용되어 답변 본문이 비어 있을 수 있습니다. 종료 사유가
CONTINUATION이면 계속 요청하세요. MAX_TOKENS에서도continuationToken이 반환될 수 있습니다. 재개하려면maxOutputTokens를 수동으로 늘리고 최신 토큰과 함께 원래 요청을 다시 보내야 합니다. 소진된 예산을 그대로 쓰면 400이 반환됩니다. 아래 “예산 소진 후 재개”를 참고하세요.- 여러 턴의 대화에서는
STOP까지 기다린 뒤 합친 전체 답변을 하나의model메시지로 이력에 추가하세요.
예제
첫 번째 요청:curl -X POST "https://direct.evolink.ai/v1beta/models/gemini-4-argon:generateContent" \
-H "Authorization: Bearer $EVOLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{ "role": "user", "parts": [{ "text": "Rust 비동기 런타임의 완전한 설계 문서를 작성해 주세요. 아키텍처, 스케줄러, I/O 드라이버, 타이머와 전체 예제 코드를 포함해 주세요." }] }
],
"generationConfig": {
"maxOutputTokens": 262144,
"thinkingConfig": { "thinkingLevel": "high" }
}
}'
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "# Rust 비동기 런타임 설계\n\n## 1. 아키텍처\n…"
}
]
},
"finishReason": "CONTINUATION",
"continuationToken": "<긴 문자열이며 그대로 보존>"
}
]
}
CONTINUATION이면 동일한 요청의 최상위에 continuationToken을 추가해 다시 보냅니다:
curl -X POST "https://direct.evolink.ai/v1beta/models/gemini-4-argon:generateContent" \
-H "Authorization: Bearer $EVOLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{ "role": "user", "parts": [{ "text": "Rust 비동기 런타임의 완전한 설계 문서를 작성해 주세요. 아키텍처, 스케줄러, I/O 드라이버, 타이머와 전체 예제 코드를 포함해 주세요." }] }
],
"generationConfig": {
"maxOutputTokens": 262144,
"thinkingConfig": { "thinkingLevel": "high" }
},
"continuationToken": "<이전 응답의 continuationToken>"
}'
CONTINUATION을 자동 처리하고 정상 완료 또는 예산 소진 시 반환합니다. 최신 토큰을 보존하며 MAX_TOKENS에서 예산을 자동으로 늘리지 않습니다:
import os
from copy import deepcopy
import requests
URL = "https://direct.evolink.ai/v1beta/models/gemini-4-argon:generateContent"
HEADERS = {"Authorization": f"Bearer {os.environ['EVOLINK_API_KEY']}"}
def generate_with_continuation(body):
request_body = deepcopy(body)
pieces = []
while True:
# 클라이언트 읽기 타임아웃은 1,200초이며 서버가 20분 연결을 유지한다는 보장은 아닙니다.
resp = requests.post(URL, headers=HEADERS, json=request_body, timeout=1200)
resp.raise_for_status()
candidates = resp.json().get("candidates", [])
if not candidates:
raise RuntimeError("응답에 후보가 없습니다. promptFeedback을 확인하세요.")
candidate = candidates[0]
for part in candidate.get("content", {}).get("parts", []):
if not part.get("thought"):
pieces.append(part.get("text", ""))
reason = candidate.get("finishReason")
token = candidate.get("continuationToken")
if reason == "CONTINUATION":
if not token:
raise RuntimeError("이어 생성이 필요하지만 continuationToken이 반환되지 않았습니다.")
request_body["continuationToken"] = token # 다른 필드는 그대로 유지
continue
return {
"text": "".join(pieces),
"finishReason": reason,
"continuationToken": token,
}
body = {
"contents": [
{"role": "user", "parts": [{"text": "Rust 비동기 런타임의 완전한 설계 문서를 작성해 주세요. 아키텍처, 스케줄러, I/O 드라이버, 타이머와 전체 예제 코드를 포함해 주세요."}]}
],
"generationConfig": {"maxOutputTokens": 262144, "thinkingConfig": {"thinkingLevel": "high"}},
}
result = generate_with_continuation(body)
print(result["text"])
print("finishReason:", result["finishReason"])
if result["finishReason"] == "MAX_TOKENS":
print("누적 출력 예산이 소진되었습니다. 토큰이 있으면 maxOutputTokens를 수동으로 늘려 재개할 수 있습니다.")
예산 소진 후 재개
이 예제는 위의generate_with_continuation, URL, HEADERS를 재사용합니다. 작은 예산으로 숫자 목록을 만든 뒤 총예산을 명시적으로 64에서 2,048로 늘립니다. 원래 contents와 다른 설정을 유지하고, 토큰을 추가하면서 예산을 늘리면 끊긴 위치에서 재개합니다.
body = {
"contents": [
{"role": "user", "parts": [{"text": "Output integers 1 through 100, one per line. Start immediately."}]}
],
"generationConfig": {"maxOutputTokens": 64, "thinkingConfig": {"thinkingLevel": "low"}},
}
first = generate_with_continuation(body)
print(first["text"], end="")
if first["finishReason"] == "MAX_TOKENS" and first["continuationToken"]:
body["continuationToken"] = first["continuationToken"]
body["generationConfig"]["maxOutputTokens"] = 2048 # 호출자가 누적 예산 증가를 명시적으로 지정
resumed = generate_with_continuation(body)
print(resumed["text"], end="")
print("\nfinishReason:", resumed["finishReason"])
else:
print("\nfinishReason:", first["finishReason"])
finishReason이 있는 마지막 청크를 읽고 종료 사유에 따라 처리합니다. CONTINUATION은 설정을 유지하고 최신 토큰으로 계속합니다. MAX_TOKENS는 재개하려는 경우 누적 예산을 수동으로 늘려야 합니다. STOP은 정상 완료입니다.
과금 및 오류
- 각 요청은 별도로 과금됩니다. 이어 생성에서는 원래 입력과 이전에 생성한 내용이 다시 입력으로 계산됩니다. 암묵적 캐시에 적중한 부분에는 캐시 요금이 적용됩니다.
- 응답의
usageMetadata는 해당 요청만 집계합니다. 총사용량은 요청별 사용량을 더합니다. 같은 스트림 안의 사용량은 누적값이므로 마지막usageMetadata만 사용하고 중간 누적값을 중복 합산하지 마세요. - 네이티브 API의 출력 사전 차감 추정에는 비스트리밍에서도
maxOutputTokens와 65,536 중 작은 값을 사용하며, 입력은 별도로 추정합니다. 비스트리밍의 실제 요청당 출력 상한은 32,768이므로 그보다 큰 예산에서는 실제 상한 기준보다 많은 금액을 확보할 수 있습니다. 최종 요금은 응답의 실제 사용량으로 정산합니다. - 유효하지 않은 토큰은 400을 반환합니다. 형식은 맞지만 내용이 유효하지 않으면
Invalid continuation token.이, 형식이 틀리면 다른 파라미터 오류가 반환될 수 있습니다. 다른 모델은continuationToken을 무시합니다. MAX_TOKENS이후 토큰을 보내더라도 소진된maxOutputTokens를 늘리지 않으면 400을 반환합니다.
인증
##모든 API는 Bearer Token 인증이 필요합니다##
API Key 받기:
API Key 관리 페이지를 방문하여 API Key를 받으세요
요청 헤더에 추가:
Authorization: Bearer YOUR_API_KEY
경로 매개변수
호출할 Gemini 텍스트 모델을 선택하세요:
| 모델 ID | 시리즈 | 포지셔닝 |
|---|---|---|
gemini-4-argon | 4 Argon | 긴 보고서 및 대규모 코드 작업. 요청당 스트리밍 최대 65,536 / 비스트리밍 32,768토큰. 네이티브 API로 이어 생성 가능하며 총량은 공유 컨텍스트의 제한을 받음 |
gemini-3.8-flash | 3.8 Flash | 소프트웨어 엔지니어링 / 에이전트 / 다단계 추론 / 멀티모달 정확도 향상 |
gemini-3.7-flash | 3.7 Flash | Pro급 agentic / 코드 생성 / 터미널 실행 |
gemini-3.6-flash | 3.6 Flash | 다단계 오케스트레이션 / 코드 리팩터링 / 범용 추론 |
gemini-3.5-flash | 3.5 Flash | 범용 Flash |
gemini-3.5-flash-lite | 3.5 Flash-Lite | 저비용 / 고처리량 / 경량 agent |
gemini-3.1-pro-preview | 3.1 Pro (Preview) | 고급 추론 |
gemini-3.1-pro-preview-customtools | 3.1 Pro · CustomTools | 고급 추론 + 사용자 지정 도구 |
gemini-3.1-flash-lite-preview | 3.1 Flash-Lite (Preview) | 저비용 |
gemini-3-pro-preview | 3.0 Pro (Preview) | 고급 추론 |
gemini-3-flash-preview | 3.0 Flash (Preview) | 범용 Flash |
gemini-2.5-pro | 2.5 Pro | 기존 ID. 2026-10-19부터 gemini-3.8-flash에서 처리되며 해당 요금으로 과금 |
gemini-2.5-flash | 2.5 Flash | 기존 ID. 2026-10-19부터 gemini-3.5-flash-lite에서 처리되며 해당 요금으로 과금 |
gemini-2.5-flash-lite | 2.5 Flash-Lite | 기존 ID. 2026-10-19부터 gemini-3.1-flash-lite-preview에서 처리되며 해당 요금으로 과금 |
gemini-4-argon, gemini-3.8-flash, gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3.1-pro-preview-customtools, gemini-3.1-flash-lite-preview, gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite "gemini-3.6-flash"
본문
List of conversation contents, supports multi-turn dialogue and multimodal input
1Show child attributes
Show child attributes
System instruction (optional), mainly text content
Show child attributes
Show child attributes
모델이 호출할 수 있는 도구로, 세 가지 유형을 지원합니다.
functionDeclarations: 함수 호출codeExecution: 코드 실행googleSearch: Google Search 기반 웹 검색.{"googleSearch": {}}를 전달하세요(camelCase;google_search는 HTTP 400 반환). 모든 Gemini 텍스트 모델에서 사용할 수 있습니다. 응답의candidates[].groundingMetadata에 검색어와 출처가 포함되며 호출당 요금이 부과됩니다.
[{ "googleSearch": {} }]
Tool calling configuration (optional)
Safety settings list (optional)
Generation configuration parameters (optional)
Show child attributes
Show child attributes
긴 출력 이어 생성 토큰(gemini-4-argon 전용). 가장 최근 응답의 candidates[0].continuationToken을 요청 최상위에 그대로 넣습니다. 원래 contents, systemInstruction, tools를 보존하고 이미 생성한 본문은 추가하지 마세요.
CONTINUATION: 모든 생성 설정을 유지하고 토큰을 다시 보냅니다.MAX_TOKENS: 토큰이 반환될 수도 있습니다. 재개 전 누적maxOutputTokens를 수동으로 늘리고 다른 설정은 유지합니다. 소진된 예산을 그대로 쓰면 400이 반환됩니다.- 유효하지 않은 토큰은 400을 반환합니다.
- 다른 모델은 이 필드를 무시합니다.
네이티브 API 전체 참조의 “긴 출력 이어 생성하기”를 참고하세요.
Cached content name, in the form cachedContents/{cachedContent}
응답
콘텐츠가 성공적으로 생성되었습니다
응답 형식 설명:
generateContent엔드포인트 사용 시,GenerateContentResponse반환 (완전한 응답을 한 번에 반환)streamGenerateContent엔드포인트 사용 시,StreamGenerateContentResponse반환 (스트리밍 응답, 콘텐츠를 청크 단위로 반환)