콘텐츠 생성 - CometAPI Documentation

POST

v1beta

models

{model}

{operator}

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

CometAPI를 통해 Gemini 네이티브 요청 형식을 사용하여 텍스트를 생성하고, 동영상 입력을 전송하며, 사고 또는 도구를 구성합니다. 예제에서는 gemini-3.8-flash을 사용합니다.

Google의 GenerateContent API 참조 에서 필드 정의와 모델별 옵션을 확인하세요. 이 페이지에서는 CometAPI 기본 URL, 인증 및 요청 예제를 보여 줍니다.

인증에는 x-goog-api-key 및 Authorization: Bearer 헤더를 모두 지원합니다.

빠른 시작

Google Gen AI SDK 또는 HTTP 클라이언트를 CometAPI와 함께 사용하려면 기본 URL과 API 키를 구성하세요:

설정	Google 기본값	CometAPI
기본 URL	`generativelanguage.googleapis.com`	`api.cometapi.com`
API 키	`$GEMINI_API_KEY`	`$COMETAPI_KEY`

다음 GenerateContent 텍스트 생성 가이드 에서 네이티브 API 예제를 확인하세요. 기본 URL을 변경할 때도 generateContent 요청 형식을 유지하세요.

동영상 입력 전송

동영상을 콘텐츠 파트로 전송합니다. 동영상 저장 위치에 따라 입력 형식을 선택하세요:

동영상 소스	요청 파트	사용 시점
로컬 동영상 파일	`inlineData`	동영상이 JSON 요청에서 base64로 전송할 수 있을 만큼 작은 경우입니다.
공개 동영상 URL	`fileData.fileUri`	인증이 필요 없는 공개 HTTPS URL을 통해 동영상을 사용할 수 있는 경우입니다.

REST 및 curl 요청에서는 inlineData.mimeType 및 fileData.fileUri처럼 camelCase 필드 이름을 사용하세요.

이 예제는 인라인 MP4 데이터를 전송합니다. <base64-encoded-mp4>을 동영상의 base64 콘텐츠로 바꾸세요:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "<base64-encoded-mp4>"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

이 예제는 꽃이 피는 공개 MP4를 분석합니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
          }
        },
        {
          "text": "Analyze this video and list the key scenes."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048,
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

사고 설정 (추론)

thinkingConfig.thinkingLevel을 사용하여 추론 깊이를 조정하세요. 아래 예시에서는 LOW 및 MEDIUM을 사용합니다.

사고 수준
사고 요약

이 예시에서는 사고 수준을 LOW로 설정합니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "How does quantum computing work?"
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "LOW"
    }
  }
}
EOF

사고 요약을 요청하려면 includeThoughts을 설정하세요. 응답에 요약이 포함되면 해당 텍스트 부분에는 thought: true이 있습니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is the 10th Fibonacci number when F(0)=0 and F(1)=1? Briefly verify the result."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 4096,
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM",
      "includeThoughts": true
    }
  }
}
EOF

thinkingBudget 는 Gemini 2.5를 포함한 호환 모델용 숫자 제어값입니다. Gemini 3 예시에서는 thinkingLevel을 사용하고 두 제어값을 모두 전송하지 마세요. 모델별 값은 Google의 사고 가이드 에서 확인하세요.

응답 스트리밍

Server-Sent Events를 수신하려면 streamGenerateContent?alt=sse을 사용하세요. 각 data: 줄에는 JSON GenerateContentResponse 객체가 포함됩니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --no-buffer \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Write a short poem about the stars"
        }
      ]
    }
  ]
}
EOF

시스템 지침 설정

응답을 안내하려면 systemInstruction을 사용하세요. 이 예시에서는 추가 텍스트 없이 하나의 방정식을 요청합니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "What is 2+2?"
        }
      ]
    }
  ],
  "systemInstruction": {
    "parts": [
      {
        "text": "You are a math tutor. Answer with exactly one equation and no other text."
      }
    ]
  }
}
EOF

JSON 출력 요청

responseMimeType을 application/json로 설정하고 responseSchema을 제공하세요. 이 예시에서는 이름과 숫자 거리를 포함하는 행성 배열을 요청합니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Return a JSON array of 3 planets with name and average_distance_from_sun_au."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "ARRAY",
      "items": {
        "type": "OBJECT",
        "properties": {
          "name": {
            "type": "STRING",
            "description": "Name of the planet."
          },
          "average_distance_from_sun_au": {
            "type": "NUMBER",
            "description": "Average distance from the Sun, in astronomical units."
          }
        },
        "required": [
          "name",
          "average_distance_from_sun_au"
        ]
      }
    }
  }
}
EOF

Google Search로 그라운딩

검색 그라운딩을 요청하려면 googleSearch 도구를 추가합니다. 이 예제는 UEFA EURO 2024 결승전 결과를 요청합니다:

curl \
  "https://api.cometapi.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  --data-binary @- <<'EOF'
{
  "contents": [
    {
      "parts": [
        {
          "text": "Use Google Search to find the winner and final score of the UEFA EURO 2024 final. Cite your sources."
        }
      ]
    }
  ],
  "tools": [
    {
      "googleSearch": {}
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 2048
  }
}
EOF

검색을 사용할 때는 후보의 groundingMetadata에서 검색 쿼리, 소스 URL, 소스와 응답 텍스트 간의 링크를 검사합니다.

대화 콘텐츠 유지

다중 턴 대화에서는 앞선 user 및 model 콘텐츠를 contents에 전송합니다. SDK 채팅 예제는 이 기록을 자동으로 유지합니다. 함수 호출의 경우 각 functionResponse에 대해 일치하는 functionCall 및 반환된 name를 포함하는 id 하나를 반환합니다. 앞선 모델 콘텐츠는 thoughtSignature 필드를 포함해 변경하지 않고 다시 전달합니다. 서명은 불투명하므로 표시된 텍스트에서 재구성하지 마세요.

응답 예제

텍스트 응답에는 생성된 콘텐츠와 토큰(Token) 사용량이 포함됩니다. 이 축약된 예제에서는 선택적 필드를 생략합니다:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

thoughtsTokenCount 응답에 사고 요약이 포함되지 않은 경우에도 내부 사고 토큰(Token)을 보고합니다. 각 콘텐츠 부분을 검사하세요. 응답에는 텍스트, 요약 또는 함수 호출(Function Calling)이 포함될 수 있습니다.

요청 형식 비교

Gemini 요청 및 응답 필드에는 네이티브 엔드포인트를 선택하세요. 자세한 내용은 채팅 완성 의 OpenAI 호환 형식을 참조하세요.

필드	Gemini 네이티브	OpenAI 호환 채팅
대화 입력	`contents` 함께 `parts`	`messages`
모델 ID	요청 경로에서	`model` 요청 본문에서
생성된 콘텐츠	`candidates` 함께 `content.parts`	`choices` 함께 `message`

인증

x-goog-api-key

string

header

필수

Your CometAPI key passed via the x-goog-api-key header. Bearer token authentication (Authorization: Bearer $COMETAPI_KEY) is also supported.

경로 매개변수

model

string

기본값:gemini-3.8-flash

필수

Gemini model ID. These examples use gemini-3.8-flash. See the Models page for available model IDs.

operator

enum<string>

기본값:generateContent

필수

Operation to perform. Use generateContent for a JSON response. For Server-Sent Events, select streamGenerateContent and set the separate alt query parameter to sse.

사용 가능한 옵션:

generateContent,

streamGenerateContent

쿼리 매개변수

alt

enum<string>

Set to sse when the operator is streamGenerateContent. Omit this parameter for generateContent.

사용 가능한 옵션:

sse

본문

application/json

contents

object[]

Conversation content. Each entry has an optional role (user or model) and a parts array. For tool results, preserve the complete preceding model content, including any thoughtSignature fields.

Show child attributes

systemInstruction

object

System instructions that guide the model's behavior across the entire conversation. Text only.

Show child attributes

tools

object[]

Tools available to the model during generation. Use googleSearch for search grounding.

Show child attributes

toolConfig

object

Configuration for tool usage, such as function calling mode.

Show child attributes

safetySettings

object[]

Safety filter settings. Override default thresholds for specific harm categories.

Show child attributes

generationConfig

object

Configuration for model generation behavior including temperature, output length, and response format.

Show child attributes

cachedContent

string

The name of cached content to use as context. Format: cachedContents/{id}. See the Gemini context caching documentation for details.

응답

200 - application/json

Successful response. For streaming requests, the response is a stream of SSE events, each containing a GenerateContentResponse JSON object prefixed with data:.

candidates

object[]

The generated response candidates.

Show child attributes

promptFeedback

object

Feedback on the prompt, including safety blocking information.

Show child attributes

usageMetadata

object

Token usage statistics for the request.

Show child attributes

modelVersion

string

The model version that generated this response.

createTime

string

The timestamp when this response was created (ISO 8601 format).

responseId

string

Unique identifier for this response.

마지막 수정일 2026년 9월 8일

import os
from google import genai

client = genai.Client(
    api_key=os.environ["COMETAPI_KEY"],
    http_options={
        "api_version": "v1beta",
        "base_url": "https://api.cometapi.com",
    },
)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents='Explain how AI works in a few words',
)

print(response.text)

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "AI learns patterns from massive amounts of data to make predictions, solve problems, and generate new content. \n\nIn short: **Data in → Patterns found → Smart predictions out.**"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 36,
    "thoughtsTokenCount": 388,
    "totalTokenCount": 433
  },
  "modelVersion": "gemini-3.8-flash"
}

​빠른 시작

​동영상 입력 전송

​사고 설정 (추론)

​응답 스트리밍

​시스템 지침 설정

​JSON 출력 요청

​Google Search로 그라운딩

​대화 콘텐츠 유지

​응답 예제

​요청 형식 비교

인증

경로 매개변수

쿼리 매개변수

본문

응답

빠른 시작

동영상 입력 전송

사고 설정 (추론)

응답 스트리밍

시스템 지침 설정

JSON 출력 요청

Google Search로 그라운딩

대화 콘텐츠 유지

응답 예제

요청 형식 비교