# Gemini 4 Carbon (openai)

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /gemini-4-carbon-openai/v1/chat/completions:
    post:
      summary: Gemini 4 Carbon (openai)
      deprecated: false
      description: >
        :::warning

        **⚠️ Chat only**


        This model currently supports chat requests only and has not yet been
        adapted for agent use. Connecting it to an agent may cause request
        errors or unexpected results.

        :::


        ### Streaming Support


        When `stream: true` is set in the request, the API returns the response
        as server-sent events (SSE) with `Content-Type: text/event-stream`. This
        enables progressive delivery: message deltas are sent as they are
        generated. Each event contains partial message content so you can render
        the response in real time.


        **Streaming Response Format:**

        - Content-Type: `text/event-stream`

        - Each event line starts with `data: ` followed by JSON

        - Events contain incremental message deltas

        - The final event indicates completion via `finish_reason`

        - The last chunk of the stream carries usage and credits_consumed,
        followed by data: [DONE].


        <CardGroup cols={2}>
          <Card title="Multimodal" icon="image">
            Text, image, video, audio, and PDF input
          </Card>
          <Card title="Real-time Search" icon="magnifying-glass">
            Google Search grounding
          </Card>
          <Card title="Streaming" icon="stream">
            Server-sent events
          </Card>
          <Card title="Flexible Roles" icon="users">
            Multiple message roles
          </Card>
        </CardGroup>


        ## Unified Media File Format


        ::: warning[]

        In the `content` array of the `messages` parameter, all media files use
        the same structure, whether they are images, videos, audio, or other
        documents:


        - The `type` field is always `"image_url"`

        - The `image_url` field name stays the same

        - Only the `url` value changes, pointing to the corresponding media file


        For example, images, videos, audio, PDFs, and other documents all use `{
        type: 'image_url', image_url: { url: '...' } }`.

        :::


        ## Tools Parameter


        `tools` is an optional array that lets you define functions the model
        can call. The array can contain multiple objects. When using function
        calling, you can declare multiple functions in the array.


        <AccordionGroup>

        <Accordion title="Function calling">

        Define custom functions with parameters. You can declare multiple
        functions in the `tools` array:


        ```json

        [
          {
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "description": "Get the current weather for a given location",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": {
                    "type": "string",
                    "description": "City and state, for example: San Francisco, CA"
                  },
                  "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                  }
                },
                "required": ["location"]
              }
            }
          },
          {
            "type": "function",
            "function": {
              "name": "get_stock_price",
              "description": "Get the current price for a given stock symbol",
              "parameters": {
                "type": "object",
                "properties": {
                  "symbol": {
                    "type": "string",
                    "description": "Stock symbol, for example: AAPL"
                  }
                },
                "required": ["symbol"]
              }
            }
          }
        ]

        ```


        ### Function declaration requirements


        To use function calling in the prompt, create a `tools` array that
        contains one or more function declarations. Define functions with JSON
        (specifically, a selected subset of the OpenAPI schema format).


        A single function declaration can include the following fields:


        - **`name`** (string, required): Unique function name (for example,
        `get_weather_forecast`, `send_email`). Use a descriptive name without
        spaces or special characters (underscore or camelCase).


        - **`description`** (string, optional but recommended): A clear,
        detailed explanation of what the function does. This is critical for the
        model to know when to call it. Be specific and provide examples when
        needed (for example, "Find movie theaters by location, optionally
        including movies currently playing.").


        - **`parameters`** (object, required): Defines the input parameters the
        function expects. Includes:
          - **`type`** (string): Overall data type; must be `"object"`.
          - **`properties`** (object): Lists each parameter, each with:
            - **`type`** (string): Parameter data type, such as `string`, `integer`, `boolean`, `array`.
            - **`description`** (string): Explains the purpose and format of the parameter. Provide examples and constraints (for example, "City and state, such as 'San Francisco, CA', or a ZIP code such as '95616'.").
            - **`enum`** (array, optional): If values come from a fixed set, list allowed values with `enum` instead of only describing them in text. This improves accuracy (for example, `"enum": ["daylight", "cool", "warm"]`).
          - **`required`** (array): An array of strings listing parameter names required for the function to run.
        </Accordion>

        </AccordionGroup>


        ## Error Responses


        Errors are returned with HTTP 200 and a JSON body {"code": <int>, "msg":
        "<reason>"}. Check code (200 = success) before reading
        choices/candidates.
      operationId: gemini-4-carbon-chat-completions
      tags:
        - docs/en/Market/Chat  Models/Gemini
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  description: >-
                    An array of message objects. Each message has a role and
                    content.


                    **Unified media file format:**


                    In the content array, all media files use the same
                    structure, whether they are images, videos, audio, or other
                    documents:


                    - The `type` field is always `"image_url"`

                    - The `image_url` field name stays the same

                    - Only the `url` value changes, pointing to the
                    corresponding media file


                    For example, images, videos, audio, PDFs, and other
                    documents all use `{ type: 'image_url', image_url: { url:
                    '...' } }`.
                  items:
                    type: object
                    x-apidog-refs:
                      01M65R3WMGR73BE1MKKE1C155F:
                        $ref: '#/components/schemas/Message'
                        x-apidog-overrides:
                          content: &ref_0
                            type: array
                            description: >-
                              Message content array that can contain text and
                              image objects. Up to 10 files are supported; more
                              than 10 files will cause an error.


                              **Unified media file format:**


                              All media files use the same structure, whether
                              they are images, videos, audio, or other
                              documents:


                              - The `type` field is always `"image_url"`

                              - The `image_url` field name stays the same

                              - Only the `url` value changes, pointing to the
                              corresponding media file


                              For example, images, videos, audio, PDFs, and
                              other documents all use `{ type: 'image_url',
                              image_url: { url: '...' } }`.
                            items:
                              oneOf:
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - text
                                      examples:
                                        - text
                                    text:
                                      type: string
                                      description: Text content of the message
                                  required:
                                    - type
                                    - text
                                  x-apidog-orders:
                                    - type
                                    - text
                                  x-apidog-ignore-properties: []
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - image_url
                                      examples:
                                        - image_url
                                    image_url:
                                      type: object
                                      properties:
                                        url:
                                          type: string
                                          format: uri
                                          description: URL of the media file
                                      required:
                                        - url
                                      x-apidog-orders:
                                        - url
                                      x-apidog-ignore-properties: []
                                  required:
                                    - type
                                    - image_url
                                  x-apidog-orders:
                                    - type
                                    - image_url
                                  x-apidog-ignore-properties: []
                        required:
                          - content
                    x-apidog-orders:
                      - 01M65R3WMGR73BE1MKKE1C155F
                    properties:
                      role:
                        type: string
                        enum:
                          - developer
                          - system
                          - user
                          - assistant
                          - tool
                        description: >-
                          Message role


                          - **developer**: Developer-provided instructions that
                          the model should follow, regardless of user messages.

                          - **system**: Developer-provided instructions that the
                          model should follow, regardless of user messages.

                          - **user**: Messages sent by end users, containing
                          prompts or additional context information.

                          - **assistant**: Messages sent by the model in
                          response to user messages.

                          - **tool**: Content of tool messages.
                      content: *ref_0
                    required:
                      - role
                      - content
                    x-apidog-ignore-properties:
                      - role
                      - content
                  minItems: 1
                stream:
                  type: boolean
                  default: false
                  description: >-
                    Default is false. Set to true to receive the response as
                    SSE.
                tools:
                  type: array
                  description: >-
                    Optional array of tools the model can call. The array can
                    contain multiple objects.


                    **Google Search**: `{"type": "function", "function":
                    {"name": "googleSearch"}}` — enable real-time information
                    retrieval via Google Search.
                  items:
                    type: object
                    description: >-
                      Tool definition.


                      - **Enhanced Network Access**: `{"type": "function",
                      "function": {"name": "googleSearch"}}`
                    properties:
                      type:
                        type: string
                        enum:
                          - function
                        description: Utility type. Must be 'function'.
                        examples:
                          - function
                      function:
                        type: object
                        description: >-
                          Function declaration: `googleSearch` for Google
                          Search, or a custom function.
                        properties:
                          name:
                            type: string
                            description: >-
                              Function name. Use `googleSearch` to enable Google
                              Search; for function calling, use the name of your
                              function.
                          description:
                            type: string
                            description: >-
                              Optional but recommended. A clear and specific
                              description of the function's purpose. Helps the
                              model understand when to call this function.
                          parameters:
                            type: object
                            description: >-
                              Defines a JSON Schema object for function
                              parameters. Required for custom functions; not
                              used by 'googleSearch'. Follows the JSON Schema
                              specification.
                            properties:
                              type:
                                type: string
                                enum:
                                  - object
                                description: Must be 'object' for function parameters
                              properties:
                                type: object
                                description: >-
                                  Map parameter names to objects defined in
                                  their JSON Schema.
                                additionalProperties:
                                  type: string
                                x-apidog-orders: []
                                properties: {}
                                x-apidog-ignore-properties: []
                              required:
                                type: array
                                items:
                                  type: string
                                description: Required parameter name array
                            required:
                              - type
                              - properties
                            x-apidog-orders:
                              - type
                              - properties
                              - required
                            x-apidog-ignore-properties: []
                        required:
                          - name
                        x-apidog-orders:
                          - name
                          - description
                          - parameters
                        x-apidog-ignore-properties: []
                    required:
                      - type
                      - function
                    x-apidog-orders:
                      - type
                      - function
                    title: The tools parameter of the chat model
                    x-apidog-ignore-properties: []
                  minItems: 0
                include_thoughts:
                  type: boolean
                  description: Whether to include thought output.
                  examples:
                    - true
                reasoning_effort:
                  type: string
                  enum:
                    - low
                    - medium
                    - high
                  description: >-
                    Thinking level. Options: low / medium / high. Default:
                    medium.
                  examples:
                    - medium
                  default: medium
              required:
                - messages
              x-apidog-orders:
                - messages
                - stream
                - tools
                - include_thoughts
                - reasoning_effort
              examples:
                - messages:
                    - role: user
                      content:
                        - type: text
                          text: What is in this image?
                        - type: image_url
                          image_url:
                            url: >-
                              https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png
                  tools:
                    - type: function
                      function:
                        name: googleSearch
                  stream: true
                  include_thoughts: true
                  response_format:
                    type: json_schema
                    json_schema:
                      name: structured_output
                      strict: true
                      schema:
                        type: object
                        properties:
                          response:
                            type: string
                        required:
                          - response
              x-apidog-ignore-properties: []
            example:
              messages:
                - role: user
                  content:
                    - type: text
                      text: What is in this image?
                    - type: image_url
                      image_url:
                        url: >-
                          https://file.aiquickdraw.com/custom-page/akr/section-images/1759055072437dqlsclj2.png
              tools:
                - type: function
                  function:
                    name: googleSearch
              stream: true
              include_thoughts: true
              reasoning_effort: medium
      responses:
        '200':
          description: Request successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the chat completion
                    examples:
                      - chatcmpl-example-123
                  object:
                    type: string
                    description: Object type
                    examples:
                      - chat.completion
                  created:
                    type: integer
                    format: int64
                    description: Unix timestamp when the completion was created
                    examples:
                      - 1677652288
                  choices:
                    type: array
                    description: Array of completion choices
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Choice index
                          examples:
                            - 0
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                              examples:
                                - assistant
                            content:
                              type: string
                              description: Message content
                          required:
                            - role
                            - content
                          x-apidog-orders:
                            - role
                            - content
                          x-apidog-ignore-properties: []
                        finish_reason:
                          type: string
                          description: Reason the completion finished
                          examples:
                            - stop
                      required:
                        - index
                        - message
                        - finish_reason
                      x-apidog-orders:
                        - index
                        - message
                        - finish_reason
                      x-apidog-ignore-properties: []
                  usage:
                    type: object
                    properties:
                      prompt_tokens:
                        type: integer
                        description: Number of tokens in the prompt
                        examples:
                          - 10
                      completion_tokens:
                        type: integer
                        description: Number of tokens in the completion
                        examples:
                          - 50
                      total_tokens:
                        type: integer
                        description: Total number of tokens
                        examples:
                          - 60
                    required:
                      - prompt_tokens
                      - completion_tokens
                      - total_tokens
                    x-apidog-orders:
                      - prompt_tokens
                      - completion_tokens
                      - total_tokens
                    x-apidog-ignore-properties: []
                  credits_consumed:
                    type: number
                    description: Credits deducted for this request
                    examples:
                      - 0.01
                x-apidog-orders:
                  - id
                  - object
                  - created
                  - choices
                  - usage
                  - credits_consumed
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: ''
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: >-
                      Response status code


                      - **200**: Success - Request has been processed
                      successfully

                      - **401**: Unauthorized - Authentication credentials are
                      missing or invalid

                      - **402**: Insufficient Credits - Account does not have
                      enough credits to perform the operation

                      - **404**: Not Found - The requested resource or endpoint
                      does not exist

                      - **408**: Timeout - No result has been returned for over
                      10 minutes.

                      - **422**: Validation Error - The request parameters
                      failed validation checks

                      - **429**: Rate Limited - Request limit has been exceeded
                      for this resource

                      - **455**: Service Unavailable - System is currently
                      undergoing maintenance

                      - **500**: Server Error - An unexpected error occurred
                      while processing the request

                      - **501**: Generation Failed - Content generation task
                      failed

                      - **505**: Feature Disabled - The requested feature is
                      currently disabled
                  msg:
                    type: string
                    description: Response message, error description when failed
                  data:
                    type: object
                    properties: {}
                    x-apidog-orders: []
                    x-apidog-ignore-properties: []
                x-apidog-orders:
                  - code
                  - msg
                  - data
                required:
                  - code
                  - msg
                  - data
                x-apidog-ignore-properties: []
              example:
                code: 500
                msg: >-
                  Server Error - An unexpected error occurred while processing
                  the request
                data: null
          headers: {}
          x-apidog-name: Error
      security: []
      x-apidog-folder: docs/en/Market/Chat  Models/Gemini
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1184766/apis/api-46858085-run
components:
  schemas:
    Message:
      type: object
      properties:
        role:
          type: string
          enum:
            - developer
            - system
            - user
            - assistant
            - tool
          description: >-
            Message role


            - **developer**: Developer-provided instructions that the model
            should follow, regardless of user messages.

            - **system**: Developer-provided instructions that the model should
            follow, regardless of user messages.

            - **user**: Messages sent by end users, containing prompts or
            additional context information.

            - **assistant**: Messages sent by the model in response to user
            messages.

            - **tool**: Content of tool messages.
        content:
          type: array
          description: >-
            Message content array that can contain text and image objects.


            **Unified Media File Format:**


            Whether it's images, videos, audio, or other document types, all
            media files use the same format structure:


            - The `type` field is always `"image_url"`

            - The `image_url` field name remains unchanged

            - The only thing that changes is the `url` value, which points to
            the corresponding media file address


            For example: images, videos, audio, PDFs, and other documents all
            use the same `{ type: 'image_url', image_url: { url: '...' } }`
            structure.
          items:
            oneOf:
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                    examples:
                      - text
                  text:
                    type: string
                    description: Text content of the message.
                required:
                  - type
                  - text
                x-apidog-orders:
                  - type
                  - text
                x-apidog-ignore-properties: []
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - image_url
                    examples:
                      - image_url
                  image_url:
                    type: object
                    properties:
                      url:
                        type: string
                        format: uri
                        description: URL of the media file.
                    required:
                      - url
                    x-apidog-orders:
                      - url
                    x-apidog-ignore-properties: []
                required:
                  - type
                  - image_url
                x-apidog-orders:
                  - type
                  - image_url
                x-apidog-ignore-properties: []
      required:
        - role
        - content
      title: The messages parameter of the chat model
      x-apidog-orders:
        - role
        - content
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes:
    BearerAuth:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All API requests require a Bearer Token. Add the header `Authorization:
        Bearer YOUR_API_KEY` to authenticate requests.
    BearerAuth1:
      type: bearer
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 请求都需要 Bearer Token。请在请求头中添加 `Authorization: Bearer YOUR_API_KEY`
        进行身份验证。
servers:
  - url: https://api.kie.ai
    description: 正式环境
security:
  - BearerAuth: []
    x-apidog:
      schemeGroups:
        - id: kn8M4YUlc5i0A0179ezwx
          schemeIds:
            - BearerAuth
      required: true
      use:
        id: kn8M4YUlc5i0A0179ezwx
      scopes:
        kn8M4YUlc5i0A0179ezwx:
          BearerAuth: []

```
