Gemini Chat Completion API 신청 및 사용

Google Gemini는 매우 강력한 AI 대화 시스템으로, 입력한 프롬프트에 따라 몇 초 만에 유창하고 자연스러운 응답을 생성할 수 있습니다. Gemini는 놀라운 지능적 지원을 제공하여 인간의 작업 효율성과 창의성을 크게 향상시킵니다. 이 문서는 Gemini Chat Completion API 사용 프로세스를 주로 설명하며, 이를 통해 공식 Gemini의 대화 기능을 쉽게 사용할 수 있습니다.

신청 프로세스

Gemini Chat Completion API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API Token을 받아야 합니다. 이를 보관해 두세요.

로그인이나 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다. 하나의 API Token으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스에 대해 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 할당량이 제공되어 무료로 체험할 수 있습니다; 할당량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.

📘 전체 문서: Gemini Chat Completion API →

기본 사용

이제 인터페이스에 해당 내용을 입력할 수 있습니다. 아래 그림과 같이 진행하세요:

이 API를 처음 사용할 때는 최소한 세 가지 내용을 입력해야 합니다. 하나는 authorization으로, 드롭다운 목록에서 선택하면 됩니다. 또 다른 매개변수는 model로, model은 Gemini 공식 모델 카테고리를 선택하는 것입니다. 여기에는 주로 6가지 모델이 있으며, 자세한 내용은 제공된 모델을 참조하세요. 마지막 매개변수는 messages로, messages는 우리가 입력하는 질문어 배열입니다. 이는 배열로, 여러 질문어를 동시에 업로드할 수 있으며, 각 질문어는 role과 content를 포함합니다. 여기서 role은 질문자의 역할을 나타내며, 우리는 user, assistant, system의 세 가지 신원을 제공합니다. 또 다른 content는 우리가 질문하는 구체적인 내용입니다. 또한 오른쪽에 해당 호출 코드 생성이 있음을 주목할 수 있으며, 코드를 복사하여 직접 실행하거나 “Try” 버튼을 클릭하여 테스트할 수 있습니다.

팁: gemini-3.x 시리즈 flash는 사고 모델로, 먼저 reasoning tokens를 소모합니다; max_tokens를 512 이상으로 설정해야 하며, 그렇지 않으면 빈 내용만 반환될 수 있습니다. gemini-3.6-flash는 현재 추천되는 Flash 모델로, 최대 100만 Token의 컨텍스트, 이미지 입력, 도구 호출 및 스트리밍 응답을 지원합니다; 현재 Chat Completions 인터페이스를 통해 호출됩니다.

호출 후, 반환된 결과는 다음과 같습니다:

{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-3.5-flash",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "reasoning_content": "**My Reasoning: Answering the User's Question**\n\nOkay, here's how I'm going to approach answering the user's question, \"What model are you?\". The core is to be direct and informative. First, I have to be clear about my origin. Then, I need to make sure the explanation is accessible, given that the user may not be familiar with technical jargon. I need to explain what a \"large language model\" actually *does*, and provide relatable examples. I know the user might be looking for a specific name, like other models have, so I'll address that directly and then wrap it up with an invitation to continue.\n\nSo, here's my plan:\n\n1.  **Lead with the key info:** I'll begin by stating that I am a large language model created by Google. That is the fundamental, most critical piece of the puzzle.\n2.  **Define the buzzword:** Then, I'll explain that \"large language model\" in simple terms. I'll explain what I *do* - process and generate text; how I *do* it - by training on huge amounts of text data; and the *goal* - to be able to communicate like a human.\n3.  **Provide context:** After that, to make the concept even clearer, I'll provide a list of examples of my capabilities. I'll mention things like answering questions, summarizing texts, writing stories, translating languages, and brainstorming ideas.\n4.  **Acknowledge the lack of a personal name:** I'll anticipate the likely question about a model name (like ChatGPT) by clearly stating that I don't have a personal name and that it's best to think of me as an AI assistant from Google.\n5.  **End with an invitation:** Lastly, I'll end with a simple, friendly question to invite further interaction and to guide the conversation.\n\nWith this approach, I am confident I can successfully answer this important question.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

반환된 결과는 여러 필드를 포함하며, 다음과 같이 설명됩니다:

id, 이번 대화 작업을 생성한 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다.
model, 선택한 Gemini 공식 모델입니다.
choices, Gemini가 질문어에 대해 제공한 응답 정보입니다.
usage: 이번 질문-응답 쌍에 대한 token 통계 정보입니다.

그 중 choices는 Gemini의 응답 정보를 포함하고 있으며, 그 안의 choices는 Gemini의 구체적인 응답 정보를 보여줍니다. 아래 그림과 같이 확인할 수 있습니다.

choices 안의 content 필드에는 Gemini의 응답 내용이 포함되어 있습니다.

이미지 이해 (다중 모달 입력)

Gemini는 원주율 다중 모달 모델로, 직접 “이미지를 볼” 수 있습니다. 이미지를 전달하려면 특정 메시지의 content를 문자열에서 내용 블록 배열로 변경하고, 배열에 text 블록과 image_url 블록을 동시에 넣으면 됩니다. 이는 OpenAI 및 공식 Gemini의 OpenAI 호환 형식과 완전히 일치합니다. image_url.url은 두 가지 형식을 지원합니다:

base64 data: URI (추천, 가장 안정적): 형식은 data:<미디어 유형>;base64,<데이터>이며, 예를 들어 data:image/jpeg;base64,/9j/4AAQ...입니다. 미디어 유형(MIME)은 data: 접두사에 이미 포함되어 있으므로, 별도의 media_type 필드는 필요하지 않습니다.
공개 접근 가능한 이미지 URL: 예를 들어 https://cdn.acedata.cloud/4hfydw.jpg입니다.

지원되는 이미지 유형: png, jpeg, webp, heic, heif입니다. Python 샘플 호출 코드 (base64 data URI):

import base64
import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

# 로컬 이미지를 base64 데이터 URI로 읽기
with open("image.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{base64_image}"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "이 이미지를 한 문장으로 설명해 주세요."},
                {"type": "image_url", "image_url": {"url": data_uri}}
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

공개적으로 접근 가능한 이미지 URL을 직접 전달할 수도 있습니다:

payload = {
    "model": "gemini-3.1-pro-preview",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "이 이미지를 한 문장으로 설명해 주세요."},
                {"type": "image_url", "image_url": {"url": "https://cdn.acedata.cloud/4hfydw.jpg"}}
            ]
        }
    ]
}

💡 image_url은 url 필드(값은 이미지 URL 또는 base64 data: URI)와 선택적 detail 필드만 허용합니다. media_type을 전달하지 마세요 — 이는 Anthropic Claude의 이미지 필드로 OpenAI / Gemini의 image_url 형식에 해당하지 않습니다.

스트리밍 응답

이 인터페이스는 스트리밍 응답도 지원하며, 이는 웹 페이지 통합에 매우 유용하여 웹 페이지에서 단어별 표시 효과를 구현할 수 있습니다. 스트리밍 응답을 원하시면 요청 헤더의 stream 매개변수를 true로 변경하면 됩니다. 변경 사항은 아래와 같지만, 호출 코드도 스트리밍 응답을 지원하도록 적절한 변경이 필요합니다.

stream을 true로 변경하면 API는 해당 JSON 데이터를 한 줄씩 반환하며, 코드 측면에서 우리는 한 줄씩 결과를 얻기 위해 적절한 수정을 해야 합니다. Python 샘플 호출 코드:

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"안녕하세요, 어떤 모델인가요?"}],
    "stream": True,
    "stream_options": {"include_usage": True}
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

출력 효과는 다음과 같습니다:

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**내 본질 정의하기**\n\n내 생각이 시작되었습니다. 사용자는 내 본질을 알고 싶어하며, 직접적으로 \"당신은 무엇인가요?\"라고 묻고 있습니다. 초기 단계는 간단했습니다: 쿼리를 식별하는 것이었습니다. 이제 나는 나의 기본 정체성을 회상합니다: 나는 대형 언어 모델입니다. 이것이 내가 전달하고자 하는 핵심 진리입니다.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**내 응답 다듬기**\n\n나는 기본 \"대형 언어 모델\" 정체성에 \"구글에 의해 훈련됨\"이라는 중요한 정보를 추가했습니다. 다음 단계는 \"대형 언어 모델\"이 실제로 무엇을 의미하는지 고려하는 것입니다. 나는 특정 기술 세부사항이나 모델 이름에 들어가지 않고 내 기능을 설명하고자 합니다. 사용자가 쉽게 이해할 수 있는 방식으로 내 기능을 전달하고 싶습니다.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**핵심 정체성 확인하기**\n\n나는 이제 내 응답을 확고히 하고 있습니다. 사용자의 모델 소속에 대한 질문은 집중된 답변이 필요합니다. 나는 \"구글에 의해 훈련됨\"이 필수적이라는 것을 파악했습니다. 특정 모델 이름을 언급하고 싶지 않지만, 이는 관련이 없습니다. 목표는 직접적이고 정확한 진술을 전달하는 것입니다. 내 목표는 기술 용어를 피하고 관련된 요점으로 바로 가는 명확하고 간결한 답변을 제공하는 것입니다.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "나는 구글에 의해 훈련된 대형 언어 모델입니다."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

응답에서 많은 data가 있으며, data 안의 choices가 최신의 답변 내용입니다. choices는 추가된 답변 내용으로, 결과에 따라 시스템에 통합할 수 있습니다. 또한 스트리밍 응답의 종료는 data의 내용을 기준으로 판단하며, 내용이 [DONE]이면 스트리밍 응답이 모두 종료된 것입니다. 반환된 data 결과는 여러 필드를 포함하고 있으며, 다음과 같이 설명됩니다:

id，이번 대화 작업의 ID로, 이번 대화 작업을 고유하게 식별하는 데 사용됩니다.
model ，선택한 Gemini 공식 모델입니다.
choices，Gemini가 질문에 대해 제공하는 답변 정보입니다.

JavaScript도 지원되며, 예를 들어 Node.js의 스트리밍 호출 코드는 다음과 같습니다:

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-2.5-pro",
    messages: [{ role: "user", content: "Hello, what model are you?" }],
    stream: true
  })
};

const response = await fetch("https://api.acedata.cloud/gemini/chat/completions", options);
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Java 샘플 코드:

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "Hello, what model are you?")));
jsonObject.put("stream", true);
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(jsonObject.toString(), mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/gemini/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());

다른 언어는 별도로 수정할 수 있으며, 원리는 모두 동일합니다.

다중 대화

다중 대화 기능을 연결하려면 messages 필드에 여러 질문을 업로드해야 하며, 여러 질문의 구체적인 예시는 아래 그림과 같습니다:

Python 샘플 호출 코드:

import requests

url = "https://api.acedata.cloud/gemini/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello there! How can I help you today?"},{"role":"user","content":"What model are you?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

여러 질문을 업로드하면 쉽게 다중 대화를 구현할 수 있으며, 다음과 같은 답변을 얻을 수 있습니다:

{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "reasoning_content": "Okay, here's how I'd approach this, thinking as a sophisticated AI:\n\nFirst, the user is directly querying my core identity: \"What model are you?\" That's a simple, straightforward question. My primary task is to provide accurate and helpful information, so I need to answer this immediately.\n\nRight off the bat, I know the answer. I *am* a large language model. That's my fundamental architecture and operational principle. I'm built on a vast network of connections and trained on a massive dataset.\n\nThen I must add the necessary context. Crucially, I have to provide the source of my training. I *was* trained by Google. That's a key identifier. It provides the user with valuable information about my origin and potential biases (though I'm trained to mitigate them).\n\nNow I must construct the response. My goal is to be factual, concise, and understandable.\n\nThe synthesized response is something like: \"I am a large language model, trained by Google.\"\n\nI have to assess the output: Does it meet the criteria? It's clear. It states what I am, it includes a critical piece of information on my origins, and it avoids jargon. No misleading promises.\n\nFinal verification: Does it actually answer the question? Yes. Is the information correct and truthful? Yes. Is it concise? Absolutely. Is the tone appropriate for any user? Yes. And, finally, this is the standard, approved response. Excellent.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

choices에 포함된 정보는 기본 사용 내용과 일치하며, 이는 Gemini가 여러 대화에 대해 응답하는 구체적인 내용을 포함하고 있어 여러 대화 내용을 바탕으로 해당 질문에 답변할 수 있습니다.

Gemini-3.0 다중 모달 모델

요청 샘플:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "이미지의 내용은 무엇인가요?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

샘플 결과:

{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.1-pro-preview",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "이 사진은 젊은 여성의 야외 반신 초상 사진입니다.\n\n다음은 사진의 주요 내용 설명입니다:\n\n*   **인물 외모**: 사진 속 소녀는 검고 부드러운 긴 직모를 가지고 있으며, 이목구비가 뚜렷하고 피부가 하얗습니다. 그녀는 부드러운 미소를 지으며 카메라를 바라보고 있습니다.\n*   **의상**: 그녀는 크림색 또는 연한 살구색의 퍼프 소매 상의를 입고 있으며, 그 위에 검은색 의상을 매치하고 있습니다(멜빵 원피스나 조끼처럼 보입니다).\n*   **빛과 그림자 분위기**: 햇빛이 왼쪽 뒤에서 비추어 그녀의 머리 위에 따뜻한 금색 광환을 형성하여 신선하고 아름다운 분위기를 만들어냅니다.\n*   **배경**: 배경은 흐릿하게 처리되어 있으며, 야외에서 촬영된 것으로 보이며, 뒤에는 넓은 도로(아스팔트 도로)와 도로 옆의 푸른 나무들이 있습니다.\n\n전체적으로 이 사진은 달콤하고 햇살이 가득한 이웃집 소녀의 느낌을 줍니다."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

물론 비디오 링크도 전달할 수 있습니다. 구체적인 입력은 다음과 같습니다:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "비디오의 내용은 무엇인가요?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

샘플 결과:

{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.1-pro-preview",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "이 비디오의 내용은 재미가 가득하며, 주로 한 **주황색 고양이**가 황혼의 시골 도로에서 자신감 있게 달리는 장면을 보여줍니다.\n\n구체적인 세부 사항은 다음과 같습니다:\n\n1.  **화면 내용**:\n    *   주인공은 주황색 줄무늬 고양이입니다.\n    *   배경은 해가 지는(또는 아침의) 순간으로, 빛이 황금색으로 부드럽습니다. 도로 옆에는 나무 울타리와 광야가 있으며, 멀리 보행자의 실루엣이 있습니다.\n    *   카메라는 낮은 각도로 촬영되어 고양이가 정면으로 달려오는 장면과 떠나는 뒷모습, 고양이의 얼굴과 무늬의 클로즈업을 번갈아 촬영합니다.\n\n2.  **소리 특징(핵심 포인트)**:\n    *   비디오의 내레이션은 매우 독특합니다. 화면은 가벼운 고양이가 달리는 모습이지만, 함께 나오는 소리는 **무겁고 리드미컬한 말발굽 소리**(또는 나막신/하이힐이 도로를 두드리는 소리)입니다.\n    *   이러한 소리는 화면과의 대비를 만들어 유머를 자아내며, 마치 이 고양이가 자신을 질주하는 경주마로 생각하는 것처럼 보입니다.\n\n총체적으로, 이는 음향과 화면의 대비를 이용해 귀여움과 웃음을 만들어내는 애완동물 비디오입니다."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

위에서 볼 수 있듯이 Gemini 3.0 모델은 다중 모달 이해를 지원합니다.

Gemini-3.1 다중 모달 모델

gemini-3.1-pro-preview는 현재 Gemini 3.1 Pro의 공식 모델 ID로, 텍스트, 이미지, 비디오 등 다중 모달 입력을 지원하며 복잡한 추론, 코딩 및 이해 작업에 적합합니다. 요청 샘플:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "이미지의 내용은 무엇인가요?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Gemini 3.1 Pro는 비디오 이해도 지원합니다:

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "비디오의 내용은 무엇인가요?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

반환 형식은 Gemini 3.0 Pro와 일치하며, 자세한 내용은 위의 Gemini-3.0 다중 모달 모델 섹션의 설명을 참조하십시오.

오류 처리

API를 호출할 때 오류가 발생하면 API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:

400 token_mismatched: 잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.
400 api_not_implemented: 잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.
401 invalid_token: 인증되지 않음, 잘못되었거나 누락된 인증 토큰입니다.
429 too_many_requests: 너무 많은 요청, 비율 제한을 초과했습니다.
500 api_error: 내부 서버 오류, 서버에서 문제가 발생했습니다.

오류 응답 예시

{
    "error": {
        "code": "400",
        "message": "잘못된 요청입니다."
    }
}

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "가져오기 실패"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

결론

이 문서를 통해 Gemini Chat Completion API를 사용하여 공식 Gemini의 대화 기능을 쉽게 구현하는 방법을 이해하셨습니다. 이 문서가 해당 API를 더 잘 연동하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 저희 기술 지원 팀에 문의해 주십시오.

시작하기

AI 채팅

AI 이미지

AI 비디오

AI 오디오

웹 & 데이터

CAPTCHA

신원

프록시

고급

Coding

Gemini Chat Completion API 신청 및 사용

신청 프로세스

기본 사용

이미지 이해 (다중 모달 입력)

스트리밍 응답

다중 대화

Gemini-3.0 다중 모달 모델

Gemini-3.1 다중 모달 모델

오류 처리

오류 응답 예시

결론

​신청 프로세스

​기본 사용

​이미지 이해 (다중 모달 입력)

​스트리밍 응답

​다중 대화

​Gemini-3.0 다중 모달 모델

​Gemini-3.1 다중 모달 모델

​오류 처리

​오류 응답 예시

​결론

신청 프로세스

기본 사용

이미지 이해 (다중 모달 입력)

스트리밍 응답

다중 대화

Gemini-3.0 다중 모달 모델

Gemini-3.1 다중 모달 모델

오류 처리

오류 응답 예시

결론