> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ttapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini Generate Content

> 使用 Gemini 原生 generateContent REST 请求和响应格式生成模型内容。

<Note>
  请求参数和响应字段与 Gemini 官方格式保持一致。完整规范请参考
  <a href="https://ai.google.dev/api/generate-content" target="_blank">Google 官方文档</a>。
</Note>

使用 `contents` 传入文本或多模态对话内容。接口同时支持系统指令、工具调用、安全设置、
缓存内容、结构化输出、思考配置以及模型支持的其他生成参数。


## OpenAPI

````yaml openapi/cn/llm.json POST /v1beta/models/{model}:generateContent
openapi: 3.1.0
info:
  title: LLM API DOCS
  version: 1.0.0
  description: TTAPI LLM API 接口服务。
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /v1beta/models/{model}:generateContent:
    post:
      summary: 生成 Gemini 内容
      description: 使用 Gemini 原生 generateContent REST 请求和响应格式生成模型内容。
      operationId: generateGeminiContent
      parameters:
        - name: model
          in: path
          required: true
          description: Gemini 模型 ID。
          schema:
            type: string
            example: gemini-3.5-flash
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeminiGenerateContentRequest'
      responses:
        '200':
          description: 请求成功，返回 Gemini GenerateContentResponse。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeminiGenerateContentResponse'
        '400':
          $ref: '#/components/responses/400Response'
        '401':
          $ref: '#/components/responses/401Response'
      security:
        - CustomApiKey: []
components:
  schemas:
    GeminiGenerateContentRequest:
      type: object
      description: Gemini generateContent 原生 REST 格式请求体。
      properties:
        contents:
          type: array
          description: 当前对话内容；多轮请求需要包含完整对话历史。
          items:
            $ref: '#/components/schemas/GeminiContent'
          minItems: 1
        tools:
          type: array
          description: 模型可以使用的函数、代码执行或受支持的内置工具。
          items:
            type: object
            additionalProperties: true
        toolConfig:
          type: object
          description: 本次请求中工具共用的配置。
          additionalProperties: true
        safetySettings:
          type: array
          description: 按安全类别设置内容拦截阈值。
          items:
            $ref: '#/components/schemas/GeminiSafetySetting'
        systemInstruction:
          $ref: '#/components/schemas/GeminiContent'
        generationConfig:
          $ref: '#/components/schemas/GeminiGenerationConfig'
        cachedContent:
          type: string
          example: cachedContents/abc123
          description: 用作上下文的缓存内容资源，格式为 cachedContents/{cachedContent}。
        serviceTier:
          type: string
          enum:
            - unspecified
            - standard
            - flex
            - priority
          description: 本次请求使用的服务层级。
        store:
          type: boolean
          description: 覆盖项目级请求日志配置。
      required:
        - contents
    GeminiGenerateContentResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            $ref: '#/components/schemas/GeminiCandidate'
        promptFeedback:
          type: object
          properties:
            blockReason:
              type: string
            safetyRatings:
              type: array
              items:
                type: object
                additionalProperties: true
        usageMetadata:
          $ref: '#/components/schemas/GeminiUsageMetadata'
        modelVersion:
          type: string
        responseId:
          type: string
        modelStatus:
          type: object
          additionalProperties: true
    GeminiContent:
      type: object
      properties:
        role:
          type: string
          enum:
            - user
            - model
            - system
          description: 内容角色；对话消息通常使用 user 或 model。
        parts:
          type: array
          items:
            $ref: '#/components/schemas/GeminiPart'
          minItems: 1
      required:
        - parts
    GeminiSafetySetting:
      type: object
      properties:
        category:
          type: string
          enum:
            - HARM_CATEGORY_HARASSMENT
            - HARM_CATEGORY_HATE_SPEECH
            - HARM_CATEGORY_SEXUALLY_EXPLICIT
            - HARM_CATEGORY_DANGEROUS_CONTENT
            - HARM_CATEGORY_CIVIC_INTEGRITY
        threshold:
          type: string
          enum:
            - HARM_BLOCK_THRESHOLD_UNSPECIFIED
            - BLOCK_LOW_AND_ABOVE
            - BLOCK_MEDIUM_AND_ABOVE
            - BLOCK_ONLY_HIGH
            - BLOCK_NONE
            - 'OFF'
      required:
        - category
        - threshold
    GeminiGenerationConfig:
      type: object
      description: 生成与输出配置；具体可用字段取决于模型。
      properties:
        stopSequences:
          type: array
          maxItems: 5
          items:
            type: string
        responseMimeType:
          type: string
          enum:
            - text/plain
            - application/json
            - text/x.enum
        responseSchema:
          type: object
          additionalProperties: true
        responseJsonSchema:
          type: object
          additionalProperties: true
        responseModalities:
          type: array
          items:
            type: string
            enum:
              - TEXT
              - IMAGE
              - AUDIO
        candidateCount:
          type: integer
          minimum: 1
          default: 1
        maxOutputTokens:
          type: integer
          minimum: 1
        temperature:
          type: number
          minimum: 0
          maximum: 2
        topP:
          type: number
          minimum: 0
          maximum: 1
        topK:
          type: integer
          minimum: 1
        seed:
          type: integer
        presencePenalty:
          type: number
        frequencyPenalty:
          type: number
        responseLogprobs:
          type: boolean
        logprobs:
          type: integer
          minimum: 0
          maximum: 20
        enableEnhancedCivicAnswers:
          type: boolean
        thinkingConfig:
          type: object
          properties:
            includeThoughts:
              type: boolean
            thinkingBudget:
              type: integer
            thinkingLevel:
              type: string
              enum:
                - THINKING_LEVEL_UNSPECIFIED
                - MINIMAL
                - LOW
                - MEDIUM
                - HIGH
        imageConfig:
          type: object
          properties:
            aspectRatio:
              type: string
            imageSize:
              type: string
              enum:
                - '512'
                - 1K
                - 2K
                - 4K
        mediaResolution:
          type: string
          enum:
            - MEDIA_RESOLUTION_UNSPECIFIED
            - MEDIA_RESOLUTION_LOW
            - MEDIA_RESOLUTION_MEDIUM
            - MEDIA_RESOLUTION_HIGH
        responseFormat:
          type: object
          additionalProperties: true
    GeminiCandidate:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/GeminiContent'
        finishReason:
          type: string
          enum:
            - FINISH_REASON_UNSPECIFIED
            - STOP
            - MAX_TOKENS
            - SAFETY
            - RECITATION
            - LANGUAGE
            - OTHER
            - BLOCKLIST
            - PROHIBITED_CONTENT
            - SPII
            - MALFORMED_FUNCTION_CALL
            - IMAGE_SAFETY
            - UNEXPECTED_TOOL_CALL
        finishMessage:
          type: string
        safetyRatings:
          type: array
          items:
            type: object
            additionalProperties: true
        citationMetadata:
          type: object
          additionalProperties: true
        groundingMetadata:
          type: object
          additionalProperties: true
        avgLogprobs:
          type: number
        index:
          type: integer
    GeminiUsageMetadata:
      type: object
      properties:
        promptTokenCount:
          type: integer
        cachedContentTokenCount:
          type: integer
        candidatesTokenCount:
          type: integer
        toolUsePromptTokenCount:
          type: integer
        thoughtsTokenCount:
          type: integer
        totalTokenCount:
          type: integer
        serviceTier:
          type: string
    GeminiPart:
      type: object
      description: 单个内容片段，可承载文本、媒体、函数调用或代码结果。
      properties:
        text:
          type: string
        inlineData:
          type: object
          properties:
            mimeType:
              type: string
              example: image/jpeg
            data:
              type: string
              description: Base64 编码数据。
          required:
            - mimeType
            - data
        fileData:
          type: object
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
          required:
            - fileUri
        functionCall:
          type: object
          properties:
            name:
              type: string
            args:
              type: object
              additionalProperties: true
        functionResponse:
          type: object
          properties:
            name:
              type: string
            response:
              type: object
              additionalProperties: true
        executableCode:
          type: object
          additionalProperties: true
        codeExecutionResult:
          type: object
          additionalProperties: true
        thought:
          type: boolean
        thoughtSignature:
          type: string
      additionalProperties: true
  responses:
    400Response:
      description: 参数错误
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
                example: '"prompt" cannot be empty.'
              data:
                type: object
            required:
              - status
              - message
    401Response:
      description: 授权失败
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: FAILED
              message:
                type: string
                example: Wrong TT-API-KEY or email is not activated.
            required:
              - status
              - message
  securitySchemes:
    CustomApiKey:
      type: apiKey
      in: header
      name: TT-API-KEY
      description: >-
        请前往 <a href='https://dashboard.ttapi.io' target='_blank'>TTAPI 控制台</a>
        获取 API 密钥。

````