TokenLab

Gemini 네이티브

콘텐츠 생성

Google Gemini API 형식을 사용하여 콘텐츠를 생성합니다

POST
/v1beta/models/{model}:generateContent

모델 목록에서 반환된 모델과 함께 Gemini 요청 및 응답 형식을 사용합니다. ProtoJSON lowerCamelCase 및 이에 해당하는 proto snake_case 필드 이름을 모두 지원합니다. 지원되는 선택적 필드 및 값은 선택한 모델에 따라 다릅니다.

경로 파라미터

modelstringpath필수

모델 이름 (예: gemini-2.5-pro, gemini-3.5-flash).

쿼리 파라미터

keystringquery

API 키 (헤더 인증의 대안).

인증

Gemini 엔드포인트는 여러 인증 방식을 지원합니다:

  • ?key=YOUR_API_KEY 쿼리 파라미터
  • x-goog-api-key: YOUR_API_KEY 헤더
  • Authorization: Bearer YOUR_API_KEY 헤더

요청 본문

contentsarray필수

parts와 선택적 role이 포함된 대화 내용입니다. 미디어 파트는 inlineData / inline_data 또는 fileData / file_data를 사용합니다. TokenLab에서 생성된 파일 및 Cache ID는 해당 파일 및 ID를 소유한 Workspace 내에서만 사용할 수 있습니다.

systemInstructionobject

모델을 위한 시스템 지침입니다.

generationConfigobject

temperature, topP, topK, maxOutputTokens, stopSequences, candidateCount, responseModalities, responseMimeType, responseSchema, thinkingConfig와 같은 생성 설정입니다. 이에 상응하는 snake_case 이름도 지원됩니다. 지원되는 값과 조합은 모델에 따라 다릅니다.

safetySettingsarray

안전 필터 설정입니다.

toolsarray

functionDeclarations와 같은 Gemini 도구입니다. 지원되는 도구 유형은 모델에 따라 다릅니다.

toolConfigobject

functionCallingConfig와 같은 도구 구성입니다.

cachedContentstring

캐시된 콘텐츠 생성을 통해 생성된 캐시된 콘텐츠의 이름입니다 (예: cachedContents/abc123). 이를 생성한 Workspace 내에서만 작동합니다.

위에 표시된 모든 lowerCamelCase 필드는 공식 proto snake_case 표기법(예: system_instruction, generation_config, safety_settings, tool_config, cached_content, file_data.file_uri, inline_data.mime_type)으로도 사용할 수 있습니다.

지원되는 메서드

Gemini 호환 API에는 모델 목록, 모델 조회, generateContent, streamGenerateContent, countTokens, Files, 캐시된 콘텐츠가 포함됩니다. Gemini Interactions 및 Live는 지원되지 않습니다.

모델을 호출하기 전에 모델의 모델 조회 응답을 확인하세요. supportedGenerationMethods에는 해당 모델이 수용하는 동작이 나열되어 있습니다.

응답

candidatesarray

생성된 콘텐츠 후보 목록입니다.

usageMetadataobject

토큰 사용량 정보입니다.

요청

curl -X POST "https://api.tokenlab.sh/v1beta/models/gemini-2.5-pro:generateContent?key=sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'

오류

  • 400 INVALID_ARGUMENT: 요청 본문이 유효하지 않거나, 모델이 Gemini 요청을 지원하지 않습니다.
  • 401 UNAUTHENTICATED: API 키가 누락되었거나 유효하지 않습니다.
  • 402 RESOURCE_EXHAUSTED: 이 요청을 처리하기에 잔액이 부족합니다.
  • 503 UNAVAILABLE: 현재 해당 모델에 사용할 수 있는 경로가 없습니다. 나중에 다시 시도하세요.

미디어 입력

미디어는 contents[].parts[] 내에 인라인 Base64 바이트(inlineData 또는 inline_data) 또는 공개 https URL(fileData 또는 file_data)로 포함합니다. 이미지, 오디오, 비디오가 지원됩니다.

이미지

인라인 이미지 바이트 사용:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

이미지 URL 사용:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Please describe this image." },
        {
          "fileData": {
            "mimeType": "image/jpeg",
            "fileUri": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}

오디오

오디오 URL 사용 (여기서는 proto snake_case 이름 사용):

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Transcribe and summarize this audio." },
        {
          "file_data": {
            "mime_type": "audio/mpeg",
            "file_uri": "https://example.com/sample.mp3"
          }
        }
      ]
    }
  ]
}

비디오

비디오 URL 사용:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Describe this video briefly." },
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://example.com/sample.mp4"
          }
        }
      ]
    }
  ]
}

응답

Response
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Hello! How can I assist you today?"}
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {"category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE"}
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 10,
    "totalTokenCount": 15
  }
}

토큰 수 계산 및 임베딩

토큰 수 계산(POST /v1beta/models/{model}:countTokens)은 API 키가 필요하며 비용이 청구되지 않습니다. 사전 계획에 토큰 수를 활용하세요. 생성 요청에 대한 요금은 해당 응답의 usageMetadata를 기준으로 청구됩니다.

임베딩 모델은 임베딩 생성(POST /v1/embeddings)을 사용합니다. 모델 조회 응답의 supportedGenerationMethods에 해당 메서드가 나열되어 있는 모델에 대해서만 embedContent 또는 batchEmbedContents를 호출하세요.

인증

AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

경로 매개변수

model*string

모델 이름 (예: gemini-2.5-pro)

쿼리 매개변수

key?string

API 키 (헤더 인증의 대안)

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"

요청 본문

application/json

네이티브 Gemini GenerateContent 요청입니다. ProtoJSON lowerCamelCase와 원본 proto snake_case 이름 모두 허용되며 혼합 요청을 포함하여 보존됩니다. 한 필드에 대해 두 가지 표기법이 모두 존재할 경우, TokenLab은 이를 병합하거나 로컬 우선순위를 선택하지 않습니다. 알 수 없는 필드는 최선의 노력으로 전달됩니다.

응답

application/json

application/json

application/json

application/json

application/json

application/json