Gemini OpenAI 호환 형식 안내

Fast-Token은 OpenAI API 프로토콜로 Google Gemini 시리즈 모델을 호출할 수 있습니다. OpenAI SDK 또는 /v1/chat/completions 기반 앱이 있다면 보통 base_url과 model만 바꿔 Gemini에 연결할 수 있으며, Gemini 네이티브 API로 다시 작성할 필요가 없습니다.

이 페이지는 사용 방법을 중심으로 설명합니다. 각 엔드포인트의 요청/응답 및 온라인 디버깅은 ChatGPT 문서와 아래 기능 대조표 링크를 참고하세요.

두 가지 연동 방식

비교 항목	OpenAI 호환 형식(이 페이지)	Gemini 네이티브 API(동일 섹션의 다른 문서)
대표 경로	POST /v1/chat/completions, POST /v1/embeddings	POST /v1beta/models/{model}:generateContent 등
요청 본문	messages, model, stream 등 OpenAI 필드	contents, generationConfig 등 Gemini 필드
적합한 경우	기존 OpenAI 클라이언트, 다중 모델 통합 게이트웨이, 빠른 이전	Gemini 전용 기능(thinkingConfig, Imagen 전용 매개변수 등)
문서 위치	이 문서 + 채팅 그룹	이 섹션의 채팅·이미지·파일 등 API 페이지

두 방식은 동일한 API Key와 게이트웨이 URL을 공유합니다. 요금은 모델 광장의 해당 모델 기준입니다.

연동 설정

게이트웨이 및 인증

• Base URL: https://fast-token.com/v1 (빠른 시작과 동일)
• 인증: 요청 헤더 Authorization: Bearer <Fast-Token_API_KEY>
• 모델 이름: 모델 광장에서 gemini가 포함된 모델 ID를 복사해 model에 입력

OpenAI SDK 사용(권장)

공식 SDK의 base_url을 Fast-Token으로 지정하면 나머지는 OpenAI와 동일합니다:

from openai import OpenAI

client = OpenAI(
    base_url="https://fast-token.com/v1",
    api_key="<Fast-Token_API_KEY>",
)

completion = client.chat.completions.create(
    model="gemini-2.5-pro",  # 以模型广场为准
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"},
    ],
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://fast-token.com/v1",
  apiKey: "<Fast-Token_API_KEY>",
});

const completion = await client.chat.completions.create({
  model: "gemini-2.5-pro",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});
console.log(completion.choices[0].message.content);

스트리밍은 요청에 stream: true를 설정하세요. 채팅 완성 생성(스트리밍) 참고.

chat 호환 형식 기능 개요

아래 기능은 모두 OpenAI 호환 경로로 접근합니다. 콘솔이나 Apifox에서는 「chat 호환 형식」으로 분류되는 경우가 많습니다. 구현상 대부분 동일한 POST /v1/chat/completions(임베딩은 POST /v1/embeddings)이며 모델과 메시지 구조로 시나리오를 구분합니다.

기능	설명	참고 문서
Gemini 이미지 생성	텍스트(및 선택적 참조 이미지)로 이미지 생성·편집	채팅 이미지 생성(비스트림)
채팅 API	표준 다중 턴 대화, 스트림/비스트림	비스트림, 스트림
채팅 API - 사고 1	모델 「사고」 출력 대화(변형 1)	스트림(extra_body.enable_thinking)
채팅 API - 사고 2	모델 「사고」 출력 대화(변형 2)	위와 동일, 모델은 모델 광장 기준
이미지 인식 API	이미지 업로드 후 이해·설명·질의	이미지 인식(스트림), 비스트림
채팅 + 파일 읽기	대화에 문서 등 첨부 분석	아래 「파일 및 멀티모달」
텍스트 임베딩	텍스트를 벡터로 변환	임베딩 생성

모델 선택

각 시나리오의 모델 ID는 모델 광장을 기준으로 하세요. gemini가 포함되고 해당 대화/이미지 인식/이미지 생성/임베딩을 지원한다고 표시된 모델을 시도하세요. 「모델 없음」 또는 미지원이면 같은 시나리오의 다른 Gemini 항목을 사용하세요.

시나리오별 사용 요점

표준 채팅

• 엔드포인트: POST /v1/chat/completions
• messages 배열로 다중 턴 유지, role은 system / user / assistant(OpenAI와 동일)
• 비스트림: stream: false 또는 stream 생략, 스트림: stream: true
• 공통 매개변수(temperature, max_tokens, top_p 등)는 OpenAI 문서와 동일, 채팅 완성 생성(비스트림) 참고

사고 모드(사고 1 / 사고 2)

일부 Gemini 사고 모델은 스트림 요청에서 확장 필드로 사고 출력을 켤 수 있습니다:

{
  "model": "gemini-2.5-pro",
  "messages": [{ "role": "user", "content": "解释相对论的核心思想" }],
  "stream": true,
  "extra_body": {
    "enable_thinking": true
  }
}

• 사고 1과 사고 2는 게이트웨이에서 서로 다른 모델 또는 라우트에 대응합니다. 모델 광장에서 「사고」로 표시된 모델을 선택해 각각 테스트하세요
• thinkingConfig(사고 토큰 예산 등)를 완전히 제어하려면 이 섹션의 Gemini 네이티브 API 문서를 사용하세요

이미지 인식(비전)

user 메시지의 content에 멀티모달 배열: text + image_url(URL 또는 Base64).

{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "这张图里有什么？" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/photo.jpg" }
        }
      ]
    }
  ],
  "stream": true
}

Base64 전송: 채팅 이미지 인식(스트림) Base64. 네이티브 inlineData 등: 이미지 이해.

이미지 생성

• 채팅 API + 이미지용 Gemini 모델로 텍스트→이미지, 참조 이미지 편집
• messages에 자연어로 요구사항 기술, 참조 이미지가 필요하면 content에 text와 image_url 함께 제공
• 요청/응답: 채팅 이미지 생성(비스트림)
• 종횡비·해상도 세밀 제어: 네이티브 이미지 생성

채팅 + 파일 읽기

OpenAI 호환 형식에서 문서, PDF 등을 멀티모달 입력의 일부로 넣을 수 있습니다(지원 MIME·크기 제한은 모델 광장 설명 기준):

1. 우선 messages[].content에서 OpenAI 멀티모달 규약으로 전달(image_url, 플랫폼이 지원하는 파일 URL/Base64)
2. 대용량·복잡 레이아웃은 네이티브 문서 이해(fileData / inlineData) 후 애플리케이션에서 대화에 병합

텍스트 임베딩

• 엔드포인트: POST /v1/embeddings
• 본문: model + input(문자열 또는 문자열 배열), OpenAI Embeddings API와 동일
• 예시·필드: 임베딩 생성, 임베딩 객체
• taskType, output_dimensionality 등 Gemini 전용 옵션: Gemini 네이티브 텍스트 임베딩

호환 형식 vs 네이티브 API 선택

요구 사항	권장
빠른 연동, OpenAI SDK/기존 코드 재사용	OpenAI 호환 형식(이 페이지)
스트림 사고, generationConfig, Google Search Grounding	네이티브 API(예: 텍스트 생성+사고-스트림, google search)
Imagen 전용 이미지, TTS, 동영상/오디오 이해	네이티브 API 해당 장
채팅+이미지 인식+이미지 생성+임베딩만, OpenAI 클라이언트 보유	OpenAI 호환 형식으로 주 경로 커버 가능

자주 묻는 질문

Q: OpenAI 문서와 완전히 같지 않은 이유는?
A: 호환 계층이 요청/응답을 OpenAI에 맞추고 내부는 Gemini입니다. OpenAI 전용 매개변수 일부는 무시될 수 있으며, 실제 모델 지원을 따르세요.

Q: model에 무엇을 넣나요?
A: 모델 광장의 전체 모델 ID(보통 gemini 접두/접미 포함), 약어 사용 금지.

Q: 스트림 응답 형식은?
A: SSE, data: {...} 행과 종료 data: [DONE], OpenAI 스트림 Chat Completions와 동일. 채팅 완성 청크 객체 참고.

Q: 전체 응답 JSON 구조는?
A: 채팅 완성 객체.

더 읽기

• 빠른 시작
• API 빠른 시작 가이드
• 모델 목록
• 이 섹션의 다른 페이지 — Gemini 네이티브 REST API