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

# Generate a video

> Submits a video generation from a prompt, a first/last frame, reference media, an earlier generation (`source_generation_id`, to extend it) or a character image plus motion video (motion-control models). `GET /v1/models/{id}` lists the inputs each mode needs; reference inputs take asset ids. Returns immediately with `status: pending`; credits are reserved now and settled when the job finishes. Poll `GET /v1/generations/{id}` until `completed` or `failed`.



## OpenAPI

````yaml /openapi.v1.json post /v1/videos
openapi: 3.1.0
info:
  contact:
    email: hello@ekly.ai
    name: Ekly
    url: https://docs.ekly.ai
  description: >-
    Generate images, video, music and speech with the same models and credits as
    the Ekly app.


    Authenticate with an organization API key from Settings → Team as a bearer
    token. Every endpoint lives under /v1 and follows the additive-only
    versioning policy at https://docs.ekly.ai/versioning.
  termsOfService: https://ekly.ai/terms
  title: Ekly API
  version: '1.0'
servers:
  - description: Production
    url: https://api.ekly.ai
security:
  - ApiKey: []
tags:
  - description: Public, versioned developer API
    name: v1
paths:
  /v1/videos:
    post:
      tags:
        - v1
      summary: Generate a video
      description: >-
        Submits a video generation from a prompt, a first/last frame, reference
        media, an earlier generation (`source_generation_id`, to extend it) or a
        character image plus motion video (motion-control models). `GET
        /v1/models/{id}` lists the inputs each mode needs; reference inputs take
        asset ids. Returns immediately with `status: pending`; credits are
        reserved now and settled when the job finishes. Poll `GET
        /v1/generations/{id}` until `completed` or `failed`.
      operationId: create_video
      parameters:
        - description: >-
            Reuse the same value when retrying the same request; a repeat
            returns the original generation without charging again. Reusing it
            with a different body returns 409.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - maxLength: 128
                type: string
              - type: 'null'
            description: >-
              Reuse the same value when retrying the same request; a repeat
              returns the original generation without charging again. Reusing it
              with a different body returns 409.
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            example:
              duration_seconds: 5
              model: seedance-2-5-fal
              prompt: A slow aerial shot over a misty pine forest at dawn
              tier: 720p
            schema:
              $ref: '#/components/schemas/CreateVideoRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerationResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              example:
                error:
                  code: unauthenticated
                  message: >-
                    This API key is not valid. Create a new one in Settings →
                    Team.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: API key missing, invalid, revoked or expired.
        '402':
          content:
            application/json:
              example:
                error:
                  code: payment_required
                  message: >-
                    Insufficient credits: this generation needs 39.6 credits and
                    12.0 are available.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not enough credits.
        '403':
          content:
            application/json:
              example:
                error:
                  code: forbidden
                  message: API keys can only call the /v1 API.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not allowed for this key or organization.
        '409':
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: >-
                    This idempotency key was already used with a different
                    request.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Idempotency key reused with a different request.
        '422':
          content:
            application/json:
              example:
                error:
                  code: validation_error
                  details:
                    - loc:
                        - body
                        - model
                      msg: Field required
                      type: missing
                  message: Request validation failed.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Request failed validation.
        '429':
          content:
            application/json:
              example:
                error:
                  code: rate_limited
                  message: Rate limit exceeded; retry after 12s.
                  trace_id: c3746d5302dc4be6b2e8fa99fa762a8c
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded; see Retry-After.
      security:
        - ApiKey: []
components:
  schemas:
    CreateVideoRequest:
      additionalProperties: false
      description: >-
        Generate a video. The same endpoint covers text-, image- and
        reference-driven generation, video extension (`source_generation_id`)
        and motion control (a motion-control model with `character_image` and
        `motion_video`). `GET /v1/models/{id}` lists which inputs each mode
        needs.
      properties:
        aspect_ratio:
          anyOf:
            - type: string
            - type: 'null'
          description: Requested aspect ratio (e.g. 16:9)
          title: Aspect Ratio
        audio:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Audio file URL for audio-to-video models like Wan 2.2
            InfiniteTalk
          title: Audio
        audio_duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            Audio duration in seconds for per-second credit calculation (Wan 2.2
            InfiniteTalk)
          title: Audio Duration Seconds
        cfg_scale:
          anyOf:
            - type: number
            - type: 'null'
          description: Kling V3/O3 CFG scale (0-1) controlling prompt adherence
          title: Cfg Scale
        character_id:
          default: 0
          description: >-
            When image has multiple people, select which character (0 =
            leftmost)
          maximum: 10
          minimum: 0
          title: Character Id
          type: integer
        character_image:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. URL of the character/avatar image whose appearance will
            be preserved. Character must have clear body proportions, no
            occlusion, and occupy >5% of image area.
          title: Character Image
        character_orientation:
          default: image
          description: >-
            'image' (match person orientation, max 10s output) or 'video' (match
            reference video orientation, max 30s output)
          title: Character Orientation
          type: string
        compression:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Precision compression-artifact removal, 0-1
          title: Compression
        duration_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          description: Requested duration seconds (5-8 for veo-2)
          title: Duration Seconds
        element_images:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. List of image URLs for Kling multi-image video
            generation
          title: Element Images
        elements:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: >-
            Kling V3/O3 elements (characters/objects) to reference as @Element1,
            @Element2
          title: Elements
        enhancement_model:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          description: Topaz enhancement model (e.g. 'Proteus', 'Starlight Precise 2.6')
          title: Enhancement Model
        face_image:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Face image URL for talking avatar models like Wan 2.2
            InfiniteTalk
          title: Face Image
        first_frame:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. First frame URL for video generation based on start/end
            frames
          title: First Frame
        frames_per_second:
          anyOf:
            - maximum: 60
              minimum: 4
              type: integer
            - type: 'null'
          description: Wan output frame rate
          title: Frames Per Second
        generate_audio:
          anyOf:
            - type: boolean
            - type: 'null'
          description: 'Enable audio generation for Veo 3+ models (default: true for Veo 3+)'
          title: Generate Audio
        grain:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Precision film grain, 0-0.1
          title: Grain
        halo:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Precision halo reduction, 0-1
          title: Halo
        idempotency_key:
          anyOf:
            - maxLength: 128
              minLength: 1
              pattern: ^\S+$
              type: string
            - type: 'null'
          description: >-
            Client-supplied non-whitespace key (1-128 chars); an identical retry
            returns the original generation without re-charging
          title: Idempotency Key
        keep_audio:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Preserve source-video audio in Kling O3 video-to-video modes
          title: Keep Audio
        keep_original_sound:
          default: false
          description: Preserve audio from the reference video
          title: Keep Original Sound
          type: boolean
        keyframes:
          anyOf:
            - items:
                $ref: '#/components/schemas/Keyframe'
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. FLUX.3 keyframes with exact 24 fps timeline positions
          title: Keyframes
        last_frame:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Last frame URL for video generation based on start/end
            frames
          title: Last Frame
        mode:
          anyOf:
            - type: string
            - type: 'null'
          description: Generation mode id declared by a matrix video model
          title: Mode
        model:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Video model identifier (veo-3.1-generate-001,
            wan-2.2-infinitetalk-fal, etc.)
          title: Model
        motion_video:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. URL of the reference video containing the motion to
            transfer. Must show realistic character with entire/upper body
            visible including head, without obstruction.
          title: Motion Video
        multi_prompt:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: Kling V3/O3 multi-shot prompts; list of {prompt, duration} shots
          title: Multi Prompt
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional negative prompt
          title: Negative Prompt
        noise:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Precision noise reduction, 0-1
          title: Noise
        num_frames:
          anyOf:
            - maximum: 120
              minimum: 40
              multipleOf: 4
              type: integer
            - type: 'null'
          description: Wan output frame count
          title: Num Frames
        previous_interaction_id:
          anyOf:
            - maxLength: 256
              type: string
            - type: 'null'
          description: >-
            Gemini Omni Flash only: chain this generation onto a previous Omni
            interaction (result_meta.interaction_id) for conversational video
            editing
          title: Previous Interaction Id
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Project scope for the generated asset (optional)
          title: Project Id
        prompt:
          default: ''
          description: >-
            Text prompt for video generation (optional for audio-to-video models
            like Wan 2.2)
          title: Prompt
          type: string
        quality:
          anyOf:
            - type: string
            - type: 'null'
          description: Video quality setting (high, medium, low, std, pro)
          title: Quality
        recover_detail:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Precision original-detail recovery, 0-1
          title: Recover Detail
        reference_audios:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Reference audio URLs; model-specific limits and
            visual-reference requirements come from the video catalog
          title: Reference Audios
        reference_image:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Single reference image URL for Kling reference tab
          title: Reference Image
        reference_images:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. List of reference image URLs for image-to-video
            generation
          title: Reference Images
        reference_names:
          anyOf:
            - additionalProperties:
                items:
                  type: string
                type: array
              type: object
            - type: 'null'
          description: >-
            User-facing aliases for Seedance references, keyed by
            reference_images/reference_videos/reference_audios
          title: Reference Names
        reference_videos:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Reference video URLs; model-specific limits come from
            the video catalog
          title: Reference Videos
        resolution:
          anyOf:
            - enum:
                - 480p
                - 580p
                - 720p
              type: string
            - type: 'null'
          description: Wan output resolution
          title: Resolution
        shot_type:
          anyOf:
            - type: string
            - type: 'null'
          description: 'Kling V3/O3 multi-shot structure: ''customize'' or ''intelligent'''
          title: Shot Type
        softness:
          anyOf:
            - type: number
            - type: 'null'
          description: Topaz Starlight Precise 2.6 softness, 1 (sharpest) to 5 (softest)
          title: Softness
        source_generation_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Completed source video generation id (same value as
            get_generation.generation_id)
          title: Source Generation Id
        source_video:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`. Source/reference video URL for Kling O3 edit/restyle
            modes
          title: Source Video
        tier:
          anyOf:
            - type: string
            - type: 'null'
          description: Quality or resolution tier id declared by a matrix video model
          title: Tier
        variant:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          description: >-
            Speed/quality variant declared by the model's `variant` parameter
            (e.g. P-Video 2 Pro: speed, quality, cost); priced by the model's
            credit matrix
          title: Variant
      title: CreateVideoRequest
      type: object
    GenerationResponse:
      description: >-
        One generation. Poll GET /v1/generations/{id} until status is completed
        or failed.
      properties:
        completed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Completed At
        created_at:
          format: date-time
          title: Created At
          type: string
        credits_charged:
          anyOf:
            - type: number
            - type: 'null'
          description: Credits actually charged; null while pending.
          title: Credits Charged
        error:
          anyOf:
            - $ref: '#/components/schemas/GenerationError'
            - type: 'null'
        id:
          examples:
            - 6f1c2d3e-9a0b-4c7d-8e1f-2a3b4c5d6e7f
          title: Id
          type: string
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
        model:
          examples:
            - seedance-2-5-fal
          title: Model
          type: string
        outputs:
          items:
            $ref: '#/components/schemas/GenerationOutput'
          title: Outputs
          type: array
        prompt:
          title: Prompt
          type: string
        status:
          enum:
            - pending
            - completed
            - failed
          title: Status
          type: string
        type:
          enum:
            - image
            - video
            - audio
          title: Type
          type: string
      required:
        - id
        - type
        - status
        - model
        - prompt
        - created_at
      title: GenerationResponse
      type: object
    ErrorResponse:
      description: Every non-2xx /v1 response.
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
        - error
      title: ErrorResponse
      type: object
    Keyframe:
      description: >-
        One FLUX 3 keyframe: an image asset pinned to a frame on the output
        timeline.
      properties:
        frame_index:
          description: Zero-based frame position on the output timeline (24 fps).
          minimum: 0
          title: Frame Index
          type: integer
        image:
          description: >-
            Asset id from `POST /v1/uploads` or a generation output's
            `asset_id`.
          title: Image
          type: string
      required:
        - image
        - frame_index
      title: Keyframe
      type: object
    GenerationError:
      properties:
        code:
          description: >-
            One of the public failure categories: rate_limited, timeout, safety,
            invalid_voice, invalid_request, billing_or_access, provider_auth,
            provider_unavailable, provider_error.
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
        - code
        - message
      title: GenerationError
      type: object
    GenerationOutput:
      properties:
        asset_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Workspace asset id for this output. Pass it as a reference input to
            chain generations.
          title: Asset Id
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          examples:
            - video/mp4
          title: Content Type
        duration_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Seconds
        height:
          anyOf:
            - type: integer
            - type: 'null'
          title: Height
        url:
          description: >-
            Download URL. Fetch promptly or store the file; URLs are not
            permanent.
          title: Url
          type: string
        width:
          anyOf:
            - type: integer
            - type: 'null'
          title: Width
      required:
        - url
      title: GenerationOutput
      type: object
    ErrorBody:
      properties:
        code:
          description: >-
            Stable machine-readable code: unauthenticated, invalid_api_key,
            payment_required, forbidden, api_key_scope, not_found, conflict,
            validation_error, rate_limited, client_error, internal_error.
          title: Code
          type: string
        details:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: >-
            Only on 422: one entry per offending field, with `loc`, `msg` and
            `type`.
          title: Details
        message:
          description: >-
            Human-readable explanation; safe to show to a developer, not meant
            for parsing.
          title: Message
          type: string
        trace_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Quote this when contacting support; it identifies the exact request.
          title: Trace Id
      required:
        - code
        - message
      title: ErrorBody
      type: object
  securitySchemes:
    ApiKey:
      bearerFormat: ek_live_…
      description: >-
        An organization API key created in Settings → Team, sent as
        `Authorization: Bearer <key>`.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.