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

# Create a chat completion

> Create an OpenAI-compatible BytePlus chat completion. Set `stream` to
`true` to receive Server-Sent Events ending with `data: [DONE]`. For a
streaming request, GENGEN always enables final usage reporting.




## OpenAPI

````yaml /openapi/gengen-v1.yaml post /chat/completions
openapi: 3.1.0
info:
  title: GENGEN API
  version: 1.0.0
  description: |
    The public GENGEN v1 API. New integrations should use normalized camelCase
    request fields and read generated media from the standard `outputs` object.
servers:
  - url: https://gengen.farm/api/gengen/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Video generation tasks
    description: Create, inspect, list, and cancel asynchronous video generation tasks.
  - name: Text generation
    description: Create OpenAI-compatible chat completions, including streamed responses.
  - name: Image generation
    description: Generate images synchronously with normalized GENGEN request fields.
  - name: Video understanding
    description: Analyze video content through the BytePlus Responses API surface.
  - name: Files
    description: Authorize direct uploads for image, video, and audio inputs.
paths:
  /chat/completions:
    post:
      tags:
        - Text generation
      summary: Create a chat completion
      description: |
        Create an OpenAI-compatible BytePlus chat completion. Set `stream` to
        `true` to receive Server-Sent Events ending with `data: [DONE]`. For a
        streaming request, GENGEN always enables final usage reporting.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
            examples:
              text:
                summary: Non-streaming text completion
                value:
                  model: seed-2-0-lite-260428
                  messages:
                    - role: user
                      content: Write a concise product summary.
                  thinking:
                    type: disabled
                  max_tokens: 300
                  stream: false
              multimodal:
                summary: Streaming multimodal completion
                value:
                  model: seed-2-0-lite-260428
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: Summarize this image.
                        - type: image_url
                          image_url:
                            url: https://example.com/image.png
                            detail: high
                  stream: true
                  stream_options:
                    include_usage: true
      responses:
        '200':
          description: |
            A JSON chat completion when `stream` is false, or an SSE stream when
            `stream` is true.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
              example:
                id: chatcmpl-example
                object: chat.completion
                model: seed-2-0-lite-260428
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: Here is a concise summary.
                    finish_reason: stop
                usage:
                  prompt_tokens: 128
                  completion_tokens: 32
                  total_tokens: 160
            text/event-stream:
              schema:
                type: string
                description: |
                  Server-Sent Events containing provider chat completion chunks.
                  The final event is `data: [DONE]`.
              example: >
                data:
                {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}


                data:
                {"id":"chatcmpl-example","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":8,"completion_tokens":1,"total_tokens":9}}


                data: [DONE]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        default:
          $ref: '#/components/responses/UnexpectedError'
components:
  schemas:
    CreateChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      description: |
        OpenAI-compatible chat completion request. Additional BytePlus Chat API
        fields are forwarded to the provider and remain model-dependent.
      properties:
        model:
          type: string
          minLength: 1
          description: Supported GENGEN text generation model ID.
          example: seed-2-0-lite-260428
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatCompletionMessage'
        stream:
          type: boolean
          default: false
          description: Return Server-Sent Events instead of one JSON completion.
        stream_options:
          $ref: '#/components/schemas/ChatStreamOptions'
        max_tokens:
          description: >-
            Maximum answer length in tokens. Do not combine with
            `max_completion_tokens`.
          oneOf:
            - type: integer
              minimum: 1
            - type: 'null'
        max_completion_tokens:
          description: Maximum answer plus reasoning length for supported reasoning models.
          oneOf:
            - type: integer
              minimum: 1
            - type: 'null'
        thinking:
          type: object
          properties:
            type:
              type: string
              description: |
                Supported values:

                - `enabled` — always use model reasoning
                - `disabled` — disable model reasoning
                - `auto` — let the model decide whether reasoning is needed
              enum:
                - enabled
                - disabled
                - auto
          additionalProperties: true
        reasoning_effort:
          description: Provider-specific reasoning depth for supported models.
          oneOf:
            - type: string
            - type: 'null'
        temperature:
          description: Sampling temperature. Model-specific restrictions can apply.
          oneOf:
            - type: number
              minimum: 0
              maximum: 2
            - type: 'null'
        top_p:
          description: Nucleus sampling threshold. Model-specific restrictions can apply.
          oneOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
        stop:
          description: One stop sequence or up to four stop sequences.
          oneOf:
            - type: string
            - type: array
              maxItems: 4
              items:
                type: string
            - type: 'null'
        frequency_penalty:
          description: Repetition penalty supported by selected models.
          oneOf:
            - type: number
              minimum: -2
              maximum: 2
            - type: 'null'
        presence_penalty:
          description: Presence penalty supported by selected models.
          oneOf:
            - type: number
              minimum: -2
              maximum: 2
            - type: 'null'
        response_format:
          type: object
          description: Text, JSON object, or JSON schema response configuration.
          additionalProperties: true
        tools:
          description: Function tools available to the model.
          oneOf:
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: 'null'
        tool_choice:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        parallel_tool_calls:
          type: boolean
        service_tier:
          type: string
          description: |
            Supported values:

            - `fast` — prioritize lower latency when supported
            - `auto` — let the provider choose the service tier
            - `default` — use standard processing
          enum:
            - fast
            - auto
            - default
      additionalProperties: true
    ChatCompletion:
      type: object
      required:
        - id
        - object
        - model
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        model:
          type: string
        service_tier:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/ChatUsage'
        moderation_hit_type:
          oneOf:
            - type: string
            - type: 'null'
      additionalProperties: true
    ChatCompletionMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          description: |
            Supported values:

            - `system` — application-level instructions
            - `user` — end-user input
            - `assistant` — model output or tool request
            - `tool` — tool execution result
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          description: Plain text, multimodal parts, or null for an assistant tool call.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ChatContentPart'
            - type: 'null'
        name:
          type: string
        tool_call_id:
          type: string
        tool_calls:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ChatStreamOptions:
      type: object
      properties:
        include_usage:
          type: boolean
          default: true
          description: GENGEN forces this to true for streamed requests.
        chunk_include_usage:
          type: boolean
          description: Include cumulative usage on each chunk when supported.
      additionalProperties: true
    ChatCompletionChoice:
      type: object
      required:
        - index
      properties:
        index:
          type: integer
        message:
          type: object
          properties:
            role:
              type: string
              example: assistant
            content:
              oneOf:
                - type: string
                - type: 'null'
            reasoning_content:
              oneOf:
                - type: string
                - type: 'null'
            tool_calls:
              type: array
              items:
                type: object
                additionalProperties: true
          additionalProperties: true
        finish_reason:
          oneOf:
            - type: string
            - type: 'null'
        logprobs:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
      additionalProperties: true
    ChatUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          minimum: 0
        completion_tokens:
          type: integer
          minimum: 0
        total_tokens:
          type: integer
          minimum: 0
        prompt_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              minimum: 0
            audio_tokens:
              type: integer
              minimum: 0
            audio_cached_tokens:
              type: integer
              minimum: 0
          additionalProperties: true
        completion_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              minimum: 0
          additionalProperties: true
      additionalProperties: true
    Error:
      type: object
      required:
        - error_code
      properties:
        error_code:
          type: string
          description: Stable machine-readable error code.
        error_params:
          type: object
          description: Optional structured error context.
          additionalProperties: true
        error:
          type: string
          description: Optional human-readable message.
      additionalProperties: true
    ChatContentPart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: |
            Common values are `text`, `image_url`, `video_url`, `input_audio`,
            and `file`.
        text:
          type: string
        image_url:
          type: object
          properties:
            url:
              type: string
            file_id:
              type: string
            detail:
              type: string
          additionalProperties: true
        video_url:
          type: object
          properties:
            url:
              type: string
            file_id:
              type: string
            fps:
              type: number
          additionalProperties: true
        input_audio:
          type: object
          additionalProperties: true
        file:
          type: object
          additionalProperties: true
      additionalProperties: true
  responses:
    BadRequest:
      description: The request body, path, or query parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: gengen.model_required
            error_params:
              field: model
            error: A model is required
    Unauthorized:
      description: The bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: gengen.auth_required
            error: Missing Authorization bearer token
    PaymentRequired:
      description: The workspace does not have enough available balance for this request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: seedance.insufficient_balance
            error: Insufficient available balance
    Forbidden:
      description: The API key is revoked, expired, or not authorized for the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: gengen.api_key_revoked
            error: GENGEN API key has been revoked
    UnexpectedError:
      description: GENGEN or an upstream provider could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: GENGEN API key
      description: A workspace API key beginning with `gengen_live_`.

````