> ## 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 Higgsfield video task

> Reserve available balance and submit asynchronous generation. Invalid parameters return 400.



## OpenAPI

````yaml openapi/higgsfield-video.yaml POST /contents/generations/tasks
openapi: 3.1.0
info:
  title: Higgsfield video API
  version: 1.0.0
  description: >-
    Independent Higgsfield Seedance 2.0 and 2.5 generation with wallet
    reservations and completion billing.
servers:
  - url: https://gengen.farm/api/gengen/v1
security:
  - bearerAuth: []
paths:
  /contents/generations/tasks:
    post:
      summary: Create a Higgsfield video task
      description: >-
        Reserve available balance and submit asynchronous generation. Invalid
        parameters return 400.
      operationId: createHiggsfieldVideoTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
            example:
              model: higgsfield-seedance-2.0
              mode: text_to_video
              prompt: A red ball resting on a wooden table.
              controls:
                duration: 4
                resolution: 480p
                ratio: '1:1'
                generateAudio: false
      responses:
        '200':
          description: Normalized GENGEN task. Poll until terminal completion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient GENGEN wallet balance.
        '503':
          description: Provider credentials or output storage are unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Request:
      type: object
      required:
        - model
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - higgsfield-seedance-2.0
            - higgsfield-seedance-2.5
        mode:
          type: string
          enum:
            - text_to_video
            - image_first_frame
            - image_first_last_frame
            - multimodal_reference
            - video_modify
            - video_extend
          description: Inferred from media when omitted. Editing and extension require 2.5.
        prompt:
          type: string
          description: Required and nonblank for text, edit and extend workflows.
        assets:
          type: object
          additionalProperties: false
          properties:
            firstFrameImage:
              type: string
              format: uri
              pattern: ^https://
              description: Public HTTPS media URL. asset:// is not supported.
            lastFrameImage:
              type: string
              format: uri
              pattern: ^https://
              description: Public HTTPS media URL. asset:// is not supported.
            sourceVideo:
              type: string
              format: uri
              pattern: ^https://
              description: Public HTTPS media URL. asset:// is not supported.
            referenceImages:
              type: array
              items:
                type: string
                format: uri
                pattern: ^https://
                description: Public HTTPS media URL. asset:// is not supported.
              maxItems: 30
            referenceVideos:
              type: array
              items:
                type: string
                format: uri
                pattern: ^https://
                description: Public HTTPS media URL. asset:// is not supported.
              maxItems: 10
            referenceAudios:
              type: array
              items:
                type: string
                format: uri
                pattern: ^https://
                description: Public HTTPS media URL. asset:// is not supported.
              maxItems: 10
            referenceVideo:
              type: string
              format: uri
              pattern: ^https://
              description: Public HTTPS media URL. asset:// is not supported.
            referenceAudio:
              type: string
              format: uri
              pattern: ^https://
              description: Public HTTPS media URL. asset:// is not supported.
          description: >-
            2.0 limits: 9 images, 3 videos, 3 audio files; requires an image or
            video reference. 2.5: 30 images, 10 videos (including source), 10
            audio files, maximum 50 total; supports audio-only reference.
        controls:
          type: object
          additionalProperties: false
          properties:
            duration:
              type: integer
              minimum: 4
              maximum: 30
              default: 5
              description: >-
                2.0 maximum 15. Omit for video_modify; editing follows source
                duration.
            resolution:
              type: string
              enum:
                - 480p
                - 720p
                - 1080p
                - 4k
              default: 720p
              description: 2.5 accepts only 480p and 720p.
            ratio:
              type: string
              enum:
                - '16:9'
                - '4:3'
                - '1:1'
                - '3:4'
                - '9:16'
                - '21:9'
                - adaptive
              description: >-
                Text/reference: explicit ratio, default 16:9. Frame/edit/extend:
                omit or adaptive.
            aspectRatio:
              type: string
              description: Alias for ratio; ratio takes precedence.
            generateAudio:
              type: boolean
              default: true
            bitrateMode:
              type: string
              enum:
                - standard
                - high
              description: 2.5 only; upstream default high.
        providerOptions:
          type: object
          additionalProperties: false
          properties:
            higgsfield:
              type: object
              additionalProperties: false
              properties:
                bitrate_mode:
                  type: string
                  enum:
                    - standard
                    - high
                  description: >-
                    Native override for 2.5. controls.bitrateMode takes
                    precedence.
    Task:
      type: object
      required:
        - id
        - model
        - status
        - outputs
      properties:
        id:
          type: string
        model:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
        outputs:
          type: object
          properties:
            videos:
              type: array
              items:
                type: string
                format: uri
            images:
              type: array
              items:
                type: string
                format: uri
        failureReason:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        error_code:
          type: string
        error_params:
          type: object
          additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````