콘텐츠로 이동
한국어
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
무료 가입
API 레퍼런스

Gemini API: BetterToken으로 텍스트와 동영상 사용하기

BetterToken의 OpenAI Chat Completions 또는 Gemini 네이티브 API로 Gemini를 호출하세요. 인증, SDK, 스트리밍, 도구, 동영상 입력과 오류 해결을 안내합니다.

BetterToken API Key로 gemini-3.8-flash와 gemini-4-argon을 호출하세요. 두 인터페이스 모두 텍스트, 동영상, 스트리밍, 도구 호출과 결과 반환을 지원합니다.

인터페이스 선택

인터페이스Base URL사용 상황
OpenAI 호환https://bettertoken.ai/v1앱에서 Chat Completions 또는 OpenAI SDK를 사용하는 경우.
Gemini 네이티브https://bettertoken.ai앱에서 Gemini 요청 필드 또는 Google GenAI SDK를 사용하는 경우.

모든 예제는 gemini-3.8-flash를 사용합니다. 다른 모델을 사용하려면 gemini-4-argon으로 바꾸세요. 현재 가격은 모델 광장에서 확인하세요. 이미지 생성은 별도의 Nano Banana 가이드를 참조하세요.

인증

BetterToken API Key를 생성한 다음 아래의 YOUR_API_KEY를 바꾸세요. 예제를 실행할 터미널에서 설정하세요.

터미널 창
export BETTERTOKEN_API_KEY="YOUR_API_KEY"
인터페이스인증 방법
OpenAI 호환Authorization: Bearer $BETTERTOKEN_API_KEY
Gemini 네이티브x-goog-api-key: $BETTERTOKEN_API_KEY(권장) 또는 Authorization: Bearer $BETTERTOKEN_API_KEY

Google AI Studio 키는 여기서 사용할 수 없습니다. BetterToken API Key를 사용하세요. 네이티브 인터페이스는 ?key=도 허용하지만 URL이 로그에 남을 수 있으므로 피하세요.

OpenAI 호환 인터페이스

POST https://bettertoken.ai/v1/chat/completions로 요청을 보내세요. SDK의 Base URL은 https://bettertoken.ai/v1입니다. SDK가 /chat/completions를 추가합니다.

curl: 기본 요청

터미널 창
curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Explain why the sky is blue."}]
  }'

choices[0].message.content에서 텍스트를 읽으세요. curl 스트리밍은 JSON 본문에 "stream": true를 추가하고 curl --no-buffer를 사용하세요.

Python: 기본 요청과 스트리밍

Python 환경에 OpenAI SDK를 설치한 다음 예제를 실행하세요.

터미널 창
python -m pip install openai

스트리밍 요청은 stream=True를 사용합니다. 각 청크의 choices[0].delta.content에서 텍스트를 읽으세요.

import os
from openai import OpenAI


client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
)
messages = [{"role": "user", "content": "Explain why the sky is blue."}]


response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
)
print(response.choices[0].message.content)


stream = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=messages,
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()

도구 호출

tools에 type: "function", 함수 name, parameters의 JSON Schema를 지정해 함수를 선언하세요. assistant가 tool_calls를 반환하면 앱에서 요청된 함수를 실행하세요.

tool_calls를 포함한 전체 assistant 메시지를 대화에 유지하세요. 각 결과에 대해 role: "tool" 메시지를 추가하세요. tool_call_id는 해당 호출 ID로 설정하고 결과는 content에 넣으세요. 갱신한 messages와 tools를 Chat Completions로 다시 보내세요.

이 인터페이스의 이미지 입력에는 다른 모델과 같이 HTTP URL 또는 data URL이 있는 image_url 콘텐츠 항목을 사용하세요.

Gemini 네이티브 인터페이스

Google GenAI SDK의 Base URL은 https://bettertoken.ai로 설정하세요. /v1beta를 추가하지 마세요. SDK가 추가합니다. 직접 HTTP 요청을 보낼 때는 아래의 전체 경로를 사용하세요.

curl: generateContent

터미널 창
curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

candidates[].content.parts[].text에서 텍스트를 읽으세요.

curl: 스트리밍

streamGenerateContent?alt=sse는 Server-Sent Events(SSE)를 반환합니다. --no-buffer는 이벤트가 도착하는 즉시 표시합니다.

터미널 창
curl --fail-with-body --no-buffer \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "Explain why the sky is blue."}]}]
  }'

Python: Google GenAI SDK

Python 환경에 google-genai를 설치하세요. 예제는 기본 요청 후 스트리밍 요청을 보냅니다.

터미널 창
python -m pip install google-genai
import os
from google import genai
from google.genai import types


client = genai.Client(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    http_options=types.HttpOptions(base_url="https://bettertoken.ai"),
)


response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
)
print(response.text)


for chunk in client.models.generate_content_stream(
    model="gemini-3.8-flash",
    contents="Explain why the sky is blue.",
):
    print(chunk.text or "", end="", flush=True)
print()

Node.js: Google GenAI SDK

@google/genai를 설치하세요. JavaScript 예제를 gemini.mjs로 저장하고 node gemini.mjs를 실행하세요.

터미널 창
npm install @google/genai
import { GoogleGenAI } from "@google/genai";


const client = new GoogleGenAI({
  apiKey: process.env.BETTERTOKEN_API_KEY,
  httpOptions: { baseUrl: "https://bettertoken.ai" },
});


const response = await client.models.generateContent({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
console.log(response.text);


const stream = await client.models.generateContentStream({
  model: "gemini-3.8-flash",
  contents: "Explain why the sky is blue.",
});
for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}
console.log();

도구 호출

tools[].functionDeclarations에 함수를 선언하세요. 모델 응답 파트의 functionCall에서 함수와 인수를 읽고 앱에서 함수를 실행하세요.

전체 모델 콘텐츠를 contents에 유지하세요. parts에 functionResponse가 포함된 role: "user" 항목을 추가하세요. 해당 함수의 name과 결과를 담은 response 객체를 지정하세요. 갱신한 contents와 tools를 generateContent로 다시 보내세요.

모델 목록

GET https://bettertoken.ai/v1beta/models로 모델 목록을 조회하세요.

터미널 창
curl --fail-with-body "https://bettertoken.ai/v1beta/models" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY"

동영상 입력

어느 예제든 보내기 전에 REPLACE_WITH_VIDEO_BASE64를 동영상의 한 줄 base64로 바꾸세요. 예제는 MP4를 사용합니다. 다른 형식은 MIME 유형과 파일명도 변경하세요.

허용되는 MIME 유형: video/mp4, video/mpeg, video/mpg, video/mov, video/avi, video/wmv, video/flv, video/mpegps.

동영상은 요청 본문에 base64로 인라인 전송하세요. base64는 원본 파일보다 데이터 크기를 약 3분의 1 늘립니다. 짧거나 압축한 클립을 사용하세요. 너무 큰 요청은 HTTP 413을 반환할 수 있습니다.

OpenAI 호환의 file.file_data는 data:video/mp4;base64, 접두사를 포함합니다. 네이티브 inlineData.data에는 접두사 없이 base64만 넣으세요.

Chat Completions: 인라인 파일

터미널 창
curl --fail-with-body "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gemini-3.8-flash",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "file", "file": {
        "filename": "clip.mp4",
        "file_data": "data:video/mp4;base64,REPLACE_WITH_VIDEO_BASE64"
      }},
      {"type": "text", "text": "Describe what happens in this video."}
    ]
  }]
}
JSON

Gemini 네이티브: inlineData

터미널 창
curl --fail-with-body \
  "https://bettertoken.ai/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "contents": [{
    "role": "user",
    "parts": [
      {"inlineData": {"mimeType": "video/mp4", "data": "REPLACE_WITH_VIDEO_BASE64"}},
      {"text": "Describe what happens in this video."}
    ]
  }]
}
JSON

사용량과 요금

Chat Completions: 추론·사고 토큰은 completion_tokens에 포함되며 출력으로 청구됩니다.

Gemini 네이티브: usageMetadata.thoughtsTokenCount는 출력으로 청구됩니다. cachedContentTokenCount는 캐시된 입력을 나타냅니다. 동영상은 입력 토큰으로 계산되며 promptTokensDetails에서 모달리티 VIDEO로 표시됩니다.

제한 사항

  • POST /v1/responses는 이 Gemini 모델들을 지원하지 않습니다. Codex CLI 등 Responses API만 사용하는 클라이언트는 호출할 수 없습니다. Chat Completions 또는 네이티브 인터페이스를 사용하세요.
  • file_id 참조와 fileData.fileUri를 사용하는 Google File API 업로드는 지원하지 않습니다. 동영상을 인라인 base64로 보내세요.

오류 해결

오류해결 방법
401BetterToken API Key와 인증 헤더를 확인하세요. 누락된 키를 추가하거나 잘못된 키를 바꾸세요.
413요청 본문이 너무 큽니다. 동영상을 줄이거나 압축하세요.
429요청 속도 제한 또는 일시적인 상위 서비스 용량 부족입니다. 대기 시간을 늘리며 다시 시도하세요.
503, 코드 model_not_found현재 사용 가능한 용량이 없습니다. 나중에 다시 시도하세요.

다른 오류는 API 오류를 참조하세요.