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

# Text-to-video

> Create a video from a text prompt.

Accepts the full video parameter set; send a text prompt in ``content``.
Returns immediately with ``{"id": "<task_id>"}``; poll
``GET /v1/video/generations/{id}`` for status.



## OpenAPI

````yaml /api/openapi.json post /v1/video/t2v
openapi: 3.1.0
info:
  title: MeshAPI
  description: One key, all AI models.
  version: 0.1.0
servers:
  - url: https://api.meshapi.ai
security:
  - BearerAuth: []
paths:
  /v1/video/t2v:
    post:
      tags:
        - Video
      summary: Text-to-video
      description: |-
        Create a video from a text prompt.

        Accepts the full video parameter set; send a text prompt in ``content``.
        Returns immediately with ``{"id": "<task_id>"}``; poll
        ``GET /v1/video/generations/{id}`` for status.
      operationId: create_video_t2v
      parameters:
        - in: header
          name: X-Mesh-Version
          required: false
          schema:
            type: string
            enum:
              - 2026-08
              - 2026-09
              - 2026-11
              - '2026-11-12'
            default: 2026-08
          example: '2026-11-12'
          description: >-
            Dated version of the API contract to pin this request to. Omit it
            and the request is served under `2026-08` — the oldest supported
            version, so an existing integration is never moved by a release. A
            malformed or unsupported value is rejected with `400
            invalid_api_version` rather than falling back silently. The version
            actually served is echoed as `X-Mesh-Version` on every response,
            including errors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '200':
          description: Task created; poll the returned id for status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoSubmitResponse'
        '401':
          description: Missing or invalid API key
        '402':
          description: Insufficient balance or spend cap reached
        '422':
          description: >-
            Invalid request, model not found, or the model cannot serve this
            request
        '429':
          description: Rate limit exceeded
      security:
        - BearerAuth: []
components:
  schemas:
    VideoGenerationRequest:
      properties:
        model:
          type: string
          title: Model
          description: Which model generates the video. Use an id from GET /v1/models.
        content:
          items:
            $ref: '#/components/schemas/VideoContentItem'
          type: array
          title: Content
          description: >-
            Your prompt, plus any images, video or audio the model should work
            from.
        previous_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Task Id
          description: >-
            Continue from one of your earlier finished videos instead of
            uploading it again.
        callback_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Callback Url
          description: >-
            We POST the finished task here when the model supports callbacks; a
            model that does not is refused rather than silently never calling
            you. Delivery is best effort and is not retried, so keep polling as
            your fallback.
        return_last_frame:
          type: boolean
          title: Return Last Frame
          description: >-
            Also return a still of the final frame, so you can chain it into the
            next clip.
          default: false
        service_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Tier
          description: >-
            Pick a faster or cheaper processing tier, where the model offers
            one.
        execution_expires_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Execution Expires After
          description: >-
            Seconds before an unfinished task is given up on. Defaults to 48
            hours.
        generate_audio:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Generate Audio
          description: Generate a soundtrack along with the picture.
        draft:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Draft
          description: >-
            Generate a quick low-resolution preview instead of the finished
            video.
        resolution:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolution
          description: >-
            Output resolution, such as 720p or 1080p, or an exact size like
            1280x720 on the models that take one.
        ratio:
          anyOf:
            - type: string
            - type: 'null'
          title: Ratio
          description: >-
            Aspect ratio, such as 16:9 or 9:16. Use adaptive to follow your
            input.
        duration:
          anyOf:
            - type: integer
              maximum: 300
            - type: 'null'
          title: Duration
          description: >-
            How long the video should be, in seconds. Use -1 to match the source
            video's length, on models that support it (byteplus Seedance 2.5).
        match_source_duration:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Match Source Duration
          description: >-
            Make the video as long as the source video you sent, instead of a
            fixed length. Cannot be combined with duration.
        fast_pretreatment:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Fast Pretreatment
          description: Skip some prompt pre-processing so generation starts sooner.
        frames:
          anyOf:
            - type: integer
            - type: 'null'
          title: Frames
          description: Exact number of frames, as an alternative to duration.
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
          description: Reuse a seed to get a similar result again.
        camera_fixed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Camera Fixed
          description: Hold the camera still instead of letting it move.
        watermark:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Watermark
          description: Add the model's watermark to the output.
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: >-
            Pin this request to one upstream provider, e.g. `bedrock`. The
            request is served by that provider or refused — never routed
            elsewhere. See `GET /v1/providers/pinnable` for the slugs this
            deployment accepts.
        safety_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Safety Identifier
          description: >-
            A stable, anonymised id for the person making the request, used for
            abuse detection.
        priority:
          anyOf:
            - type: integer
              maximum: 9
              minimum: 0
            - type: 'null'
          title: Priority
          description: Nudge this task ahead of your other queued tasks.
        external_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Task Id
          description: >-
            Your own id for this task, echoed back so you can match it to your
            records.
        multi_shot:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Multi Shot
          description: Let the model compose the video as several shots.
        negative_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Negative Prompt
          description: What to keep out of the generated video.
        guidance_scale:
          anyOf:
            - type: number
              maximum: 10
              minimum: 1
            - type: 'null'
          title: Guidance Scale
          description: >-
            How closely to follow the prompt. Higher stays nearer your wording;
            lower gives the model more freedom.
        prompt_extend:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Prompt Extend
          description: >-
            Let the model expand your prompt with extra detail before it
            generates.
        style:
          anyOf:
            - type: string
            - type: 'null'
          title: Style
          description: A named visual style, on models that offer them.
        movement_amplitude:
          anyOf:
            - type: string
            - type: 'null'
          title: Movement Amplitude
          description: How much the subjects in frame are allowed to move.
        bgm:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Bgm
          description: Add background music to the generated video.
        keep_original_sound:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Keep Original Sound
          description: >-
            Keep the audio from your source video instead of generating new
            audio.
        audio_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Audio Type
          description: 'Which kinds of sound to generate: speech, effects, or both.'
        output_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Format
          description: >-
            Container for the returned file. The accepted values are the model's
            own and the value is passed through unchecked.
        omni_reference_task_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Omni Reference Task Type
          description: >-
            Say up front whether you are generating from references, editing a
            video, or extending one, so a mismatch is caught when you submit
            rather than failing later.
        web_search:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Web Search
          description: Let the model look up current details mentioned in your prompt.
        bitrate_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Bitrate Mode
          description: Encode at a higher bitrate for a cleaner picture and a larger file.
        num_inference_steps:
          anyOf:
            - type: integer
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Num Inference Steps
          description: >-
            How many refinement steps to run. More can improve quality and takes
            longer.
        enable_safety_checker:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enable Safety Checker
          description: Run the model's own content check on the result.
        thinking_level:
          anyOf:
            - type: string
            - type: 'null'
          title: Thinking Level
          description: >-
            How much the model reasons about your prompt before it starts
            generating.
        tags:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Tags
          description: >-
            Your own labels for this request, echoed back on the usage row and
            available as a filter and a group-by dimension in the usage API.
            String keys to string values. Never put personal or sensitive data
            here — tags are stored with the usage record and are not redacted.
          examples:
            - env: prod
              feature: summariser
      type: object
      required:
        - model
        - content
      title: VideoGenerationRequest
      example:
        callback_url: https://webhook.site/your-id
        content:
          - text: >-
              A girl holding a fox, the girl opens her eyes and gently looks at
              the camera.
            type: text
          - image_url:
              url: https://example.com/reference.png
            type: image_url
        duration: 5
        generate_audio: true
        model: byteplus/dreamina-seedance-2-0
        ratio: adaptive
        watermark: false
    VideoSubmitResponse:
      properties:
        id:
          type: string
          title: Id
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        status:
          type: string
          title: Status
          default: queued
        error:
          anyOf:
            - $ref: '#/components/schemas/VideoTaskError'
            - type: 'null'
        created_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: integer
            - type: 'null'
          title: Updated At
        content:
          anyOf:
            - $ref: '#/components/schemas/VideoTaskContent'
            - type: 'null'
        seed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Seed
        resolution:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolution
        ratio:
          anyOf:
            - type: string
            - type: 'null'
          title: Ratio
        duration:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration
        frames:
          anyOf:
            - type: integer
            - type: 'null'
          title: Frames
        framespersecond:
          anyOf:
            - type: integer
            - type: 'null'
          title: Framespersecond
        generate_audio:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Generate Audio
        billed_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Billed Seconds
        billed_resolution:
          anyOf:
            - type: string
            - type: 'null'
          title: Billed Resolution
        billed_usd:
          anyOf:
            - type: number
            - type: 'null'
          title: Billed Usd
        settled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Settled
        safety_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Safety Identifier
        priority:
          anyOf:
            - type: integer
            - type: 'null'
          title: Priority
        draft:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Draft
        draft_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Draft Task Id
        service_tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Service Tier
        execution_expires_after:
          anyOf:
            - type: integer
            - type: 'null'
          title: Execution Expires After
        usage:
          anyOf:
            - $ref: '#/components/schemas/VideoTaskUsage'
            - type: 'null'
        unsupported_params:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Unsupported Params
        dropped_parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/DroppedParameter'
              type: array
            - type: 'null'
          title: Dropped Parameters
      type: object
      required:
        - id
      title: VideoSubmitResponse
      description: >-
        The submit response, which carries one field retrieval cannot.


        [internal]. `unsupported_params` is the parameters the caller sent that
        the

        SERVED provider drops — knowable only at submit, and reconstructing it
        on a

        later read would mean persisting it per task. It is on a subclass rather
        than

        on `VideoTaskResponse` because that model is also what the poll and list

        paths return AND what upstream payloads are parsed into, so a field
        there

        would appear as a null on responses that can never populate it.


        Null (not absent) when nothing was dropped, like every other optional
        field.
    VideoContentItem:
      properties:
        type:
          type: string
          title: Type
          description: >-
            The kind of media: text, image_url, video_url, audio_url or
            document_url.
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Prompt text. Several text items are joined together.
        image_url:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Image Url
          description: 'An image, given as {"url": ...} — a public URL or a data URI.'
        video_url:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Video Url
          description: 'A video, given as {"url": ...} — a public URL or a data URI.'
        audio_url:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Audio Url
          description: 'An audio clip, given as {"url": ...} — a public URL or a data URI.'
        document_url:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Document Url
          description: >-
            A document, given as {"url": ...} — a public URL the model reads for
            reference. Only some models accept one; the rest refuse the request
            rather than generating without it.
        draft_task:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Draft Task
          description: A draft task to build the finished video from.
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: >-
            What this media is for: first_frame, last_frame, reference_image,
            reference_video, reference_audio, reference_document, or one of the
            finer scene_image, source_video and background_audio. Omit it and an
            image is treated as the first frame, a video as a reference video,
            audio as reference audio, and a document as a reference document.
        subject:
          anyOf:
            - type: string
              pattern: ^[A-Za-z0-9_-]{1,64}$
            - type: 'null'
          title: Subject
          description: >-
            Groups several references into one character or object. Items
            sharing a name form one group, the first image in it is the main
            view, and @name in your prompt refers to it. 1-64 characters:
            letters, digits, _ or -.
        frame_index:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Frame Index
          description: >-
            Show this image at an exact frame number, counting from 0 at the
            start of the video. Only on a reference_image, and only one image
            per frame.
        timestamp:
          anyOf:
            - type: number
              maximum: 300
              minimum: 0
            - type: 'null'
          title: Timestamp
          description: >-
            Show this image at a moment in the video, in seconds from the start.
            Only on a reference_image, and only one image per moment.
      type: object
      required:
        - type
      title: VideoContentItem
      description: >-
        A single item in the content array.


        ``type`` is the modality (``text``, ``image_url``, ``video_url``,
        ``audio_url``,

        ``draft_task``); ``role`` is what the model should do with it. The role
        spellings

        callers send through ``type`` instead (``refer_image``, ``image_tail``,
        kling's

        omni slots) stay permanent aliases — see
        ``app.providers.video_content``.


        ``frame_index``/``timestamp`` pin a reference image to one moment of the
        video;

        a pinned image is still forwarded as an ordinary reference to models
        that

        cannot pin one.


        ``scene_image``/``source_video``/``background_audio`` NARROW an ordinary
        reference

        role, so a model without the finer slot still receives the media as that
        reference.

        ``reference_document`` narrows nothing — no other holder carries a
        document — so a

        model that cannot read one refuses the request.
    VideoTaskError:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: VideoTaskError
    VideoTaskContent:
      properties:
        video_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Video Url
        last_frame_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Frame Url
      type: object
      title: VideoTaskContent
    VideoTaskUsage:
      properties:
        completion_tokens:
          type: integer
          title: Completion Tokens
        total_tokens:
          type: integer
          title: Total Tokens
      type: object
      required:
        - completion_tokens
        - total_tokens
      title: VideoTaskUsage
    DroppedParameter:
      properties:
        name:
          type: string
          title: Name
        reason:
          type: string
          title: Reason
        offering:
          anyOf:
            - type: string
            - type: 'null'
          title: Offering
        class:
          anyOf:
            - $ref: '#/components/schemas/ParamClass'
            - type: 'null'
      type: object
      required:
        - name
        - reason
      title: DroppedParameter
      description: >-
        One parameter the caller sent that the served offering cannot accept.


        [internal]. Generalises video's `unsupported_params` (names only): a
        drop is a

        response the caller paid for that ignored what they asked for, so it
        carries

        why, and against which offering. `offering` names the model the decision
        was

        graded against — which upstream served it is internal (see
        routing/headers.py).
    ParamClass:
      type: string
      enum:
        - advisory
        - output_semantic
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Enter your MeshAPI key (`rsk_...`) or, for the admin-keys endpoints, a
        dashboard session token — sent as `Authorization: Bearer <token>`.

````

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