> ## 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 video understanding response

> Analyze a video with the BytePlus Responses API. Supply a
provider-recognized `file_id`, a public URL, or a Base64 data URL.
Streaming is not supported; the upstream Responses API object is returned
as a single JSON document.


## OpenAPI

````yaml /openapi/gengen-v1.yaml post /responses
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:
  /responses:
    post:
      tags:
        - Video understanding
      summary: Create a video understanding response
      description: >
        Analyze a video with the BytePlus Responses API. Supply a

        provider-recognized `file_id`, a public URL, or a Base64 data URL.

        Streaming is not supported; the upstream Responses API object is
        returned

        as a single JSON document.
      operationId: createVideoUnderstandingResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVideoUnderstandingResponseRequest'
            examples:
              fileId:
                summary: Analyze an uploaded video
                value:
                  model: seed-2-0-lite-260428
                  input:
                    - role: user
                      content:
                        - type: input_video
                          file_id: file-20251018abcdefg
                        - type: input_text
                          text: Describe the sequence of actions in the video.
              videoUrl:
                summary: Analyze a public video URL
                value:
                  model: seed-2-0-lite-260428
                  input:
                    - role: user
                      content:
                        - type: input_video
                          video_url: https://example.com/input-video.mp4
                          fps: 1
                        - type: input_text
                          text: Describe the video.
      responses:
        '200':
          description: A completed BytePlus Responses API object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoUnderstandingResponse'
              example:
                id: resp_01JCWexample
                object: response
                created_at: 1745380000
                status: completed
                model: seed-2-0-lite-260428
                output:
                  - type: message
                    role: assistant
                    content:
                      - type: output_text
                        text: A chef slices vegetables, then places them in a bowl.
                usage:
                  input_tokens: 2048
                  output_tokens: 256
                  total_tokens: 2304
        '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:
    CreateVideoUnderstandingResponseRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: |
            Supported values:

            - `seed-2-0-lite-260428` — Seed 2.0 Lite
            - `dola-seed-2-1-turbo-260628` — Seed 2.1 Turbo
            - `seed-2-0-pro-260328` — Seed 2.0 Pro
          enum:
            - seed-2-0-lite-260428
            - dola-seed-2-1-turbo-260628
            - seed-2-0-pro-260328
        input:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ResponseInputMessage'
        caching:
          type: object
          description: Optional provider caching configuration.
          additionalProperties: true
        max_output_tokens:
          type: integer
          minimum: 1
        metadata:
          type: object
          additionalProperties: true
        temperature:
          type: number
        top_p:
          type: number
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_choice:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
      additionalProperties: true
    VideoUnderstandingResponse:
      type: object
      required:
        - id
      description: The BytePlus Responses API result, returned without reshaping.
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        created_at:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        status:
          type: string
        model:
          type: string
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        output_text:
          type: string
          description: Convenience text output when supplied by the provider.
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        error:
          oneOf:
            - type: object
              additionalProperties: true
            - type: 'null'
      additionalProperties: true
    ResponseInputMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          example: user
        content:
          type: array
          minItems: 1
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponseInputVideo'
              - $ref: '#/components/schemas/ResponseInputText'
      additionalProperties: true
    ResponsesUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        total_tokens:
          type: integer
          minimum: 0
        input_tokens_details:
          type: object
          additionalProperties: true
        output_tokens_details:
          type: object
          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
    ResponseInputVideo:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          const: input_video
        file_id:
          type: string
          description: Provider-recognized reusable file identifier.
        video_url:
          type: string
          format: uri
          description: Public video URL or Base64 data URL.
        fps:
          type: number
          minimum: 0.2
          maximum: 5
          default: 1
          description: Frames per second sampled for model input.
      anyOf:
        - required:
            - file_id
        - required:
            - video_url
      additionalProperties: true
    ResponseInputText:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          const: input_text
        text:
          type: string
          minLength: 1
      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_`.

````