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

# Berry 1.0 Video Generation

> Create an asynchronous Berry1.0 video generation task.

At least one of `prompt`, a keyframe field or a reference field must be provided.

## Overview

Generate videos with the Berry 1.0 all-in-one model (`berry-1.0`). A single `generation` endpoint covers
three capability sets — the media fields you send decide which one runs:

| Media fields sent                                                              | Capability                          |
| :----------------------------------------------------------------------------- | :---------------------------------- |
| none (`prompt` only)                                                           | Text-to-video                       |
| `first_frame` and/or `last_frame`                                              | Image-to-video (keyframe mode)      |
| `reference_images` / `reference_videos` / `reference_audios` / `file` / `link` | Reference-to-video (reference mode) |

**Keyframe mode and reference mode are mutually exclusive** — a single request cannot mix fields from
both sides.

## Key Features

* Text-to-video, keyframe-driven image-to-video, and multi-modal reference-to-video in one endpoint
* Three resolutions (480p / 720p / 1080p), case-insensitive
* Six aspect ratios plus `adaptive`, which derives the ratio from intent and input media
* 2–30 second duration, or `-1` for smart duration picked by the model
* Audio output on by default — **pricing is identical whether audio is on or off**
* Image inputs accept both **URL and Base64**; video / audio inputs are **URL only**
* Reproducible generation with `seed`
* Prompt rewriting on by default — set `prompt_extend: false` to stay close to the literal
  prompt text

## Prompt Reference Syntax

In reference mode the `prompt` may refer to inputs by index — "Image 1" or "Video 1". Images, videos
and audios are **counted separately per field**, in array order: the
first item of `reference_images` is "Image 1", the first item of `reference_videos` is "Video 1".

## Image Input Formats

`first_frame`, `last_frame` and every item of `reference_images` accept three shapes, and the three may
be mixed within one `reference_images` array:

1. A public HTTP/HTTPS **URL**
2. A **data URI** — `data:image/png;base64,iVBORw0KGgo...`
3. A **bare Base64** string with no prefix

`reference_videos` and `reference_audios` are **URL only** — Base64 is not accepted there, because a
100MB video would inflate the request body to roughly 133MB.

## Output Ownership

All content generated through this API belongs entirely to the user. MuleRouter claims no ownership
rights over any outputs.

## Example Requests

### Text-to-Video

```json theme={null}
{
  "prompt": "A kitten runs across a rooftop under the moonlight, city neon flickering in the distance, cinematic quality, smooth camera movement.",
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}
```

### First-Frame Image-to-Video

```json theme={null}
{
  "prompt": "A graffiti youth comes alive from a concrete wall and performs a fast-paced rap under a lone street lamp at night.",
  "first_frame": "https://example.com/rap.png",
  "resolution": "720p",
  "duration": 5
}
```

### First and Last Frame

```json theme={null}
{
  "prompt": "A young girl gradually shifts from a smile to laughter, the camera slowly pushes in, background light warms from cool to warm tones.",
  "first_frame": "https://example.com/first.png",
  "last_frame": "https://example.com/last.jpg",
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5
}
```

### First Frame via Base64

```json theme={null}
{
  "prompt": "The scene comes alive, gentle camera push-in",
  "first_frame": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "resolution": "720p",
  "duration": 5
}
```

### Reference-to-Video (Multi-Subject)

```json theme={null}
{
  "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, 'The sunshine is so nice today.' Image 1, holding Image 2, walks past Video 1 and places Image 2 on the table.",
  "reference_images": [
    "https://example.com/girl.jpg",
    "https://example.com/object2.png",
    "https://example.com/object3.png",
    "https://example.com/chair4.png"
  ],
  "reference_videos": ["https://example.com/role.mp4"],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 10
}
```

### Smart Duration with Silent Output

```json theme={null}
{
  "prompt": "Cinematic drone shot over a snowy mountain range",
  "duration": -1,
  "audio": false,
  "seed": 42
}
```

### Literal Prompt (Rewriting Disabled)

```json theme={null}
{
  "prompt": "A golden retriever running through a field of sunflowers at sunset, cinematic lighting, camera slowly pushes in, warm rim light on the fur",
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "prompt_extend": false
}
```

## File and Link Inputs

Both fields are optional single HTTP/HTTPS URL strings and belong to reference mode. They cannot be combined with `first_frame` or `last_frame`, and `file` and `link` cannot be sent together.

These combinations are mutually exclusive in the public contract and JSON Schema. The gateway does not synchronously reject combinations involving `file` or `link`; it forwards them to the upstream service, which reports incompatibility through the asynchronous task error.

### File URL

`file` supports docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, and md files up to 100MB. PDF, DOCX, DOC, PPTX, PPT, KEY, and PAGES files are limited to 50 pages.

```json theme={null}
{
  "prompt": "Create a product video from this brief",
  "file": "https://example.com/product-brief.pdf",
  "resolution": "1080p",
  "duration": 10
}
```

### Link URL

`link` must point to a public web page that is accessible without authentication.

```json theme={null}
{
  "prompt": "Create a news summary video from this article",
  "link": "https://example.com/articles/product-launch",
  "resolution": "1080p",
  "duration": 10
}
```

## Pricing

Billed on one dimension — **resolution unit price × billed duration in seconds**.

| Resolution      |       Unit price |
| :-------------- | ---------------: |
| 480p            | \$0.050 / second |
| 720p            | \$0.100 / second |
| 1080p (default) | \$0.200 / second |

Both the input video and the output video are billed, by video seconds:

**billed duration = input video duration + output video duration**

* **Input video duration** — the actual duration, in seconds, of the video supplied in
  `reference_videos`; a request with no video input contributes 0 seconds here
* **Output video duration** — the duration, in seconds, of the video that was successfully generated
* A **failed task is not billed**
* `audio: false` does **not** reduce the price

## Parameters

### prompt

* **Type**: string, conditionally required
* **Max length**: 20000 characters
* Over-length prompts are **not rejected** — they are passed through and truncated upstream
* At least one of `prompt`, a keyframe field, or a reference field must be provided

### first\_frame / last\_frame

* **Type**: string (URL, data URI, or bare Base64), optional
* At most one image each; used strictly as the first / last frame of the video
* Keyframe mode — cannot be combined with any reference-mode field

### reference\_images

* **Type**: array of strings (URL, data URI, or bare Base64 — mixable), optional
* **Max items**: 10
* Reference mode — cannot be combined with keyframe fields

### reference\_videos

* **Type**: array of URI strings, optional. **URL only, no Base64**
* **Max items**: 5, total duration ≤ 15s
* This gateway checks only the recognizable file extension (`.mp4` / `.mov`); extensionless URLs such
  as signed links are passed through

### reference\_audios

* **Type**: array of URI strings, optional. **URL only, no Base64**
* **Max items**: 5, total duration ≤ 15s
* Extension check is `.wav` / `.mp3`; extensionless URLs are passed through

### resolution

* **Options**: `480p` / `720p` / `1080p` (case-insensitive)
* **Default**: `1080p`

### ratio

* **Options**: `adaptive` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16` (case-insensitive)
* **Default**: `adaptive`, which derives the ratio from intent and input media

### duration

* **Range**: integer 2–30 inclusive, or `-1` for smart duration
* **Default**: 5
* With video input, the combined input + output duration must be ≤ 30s (validated upstream)

### audio

* **Type**: boolean
* **Default**: `true`
* Whether the output video carries an audio track. **Pricing is identical either way.**

### seed

* **Range**: 0–2147483647, nullable
* **Default**: `null` (auto-generated seed)

### prompt\_extend

* **Type**: boolean
* **Default**: `true`
* Whether upstream rewrites (expands) the prompt before generation. Rewriting usually improves motion
  and cinematography on short prompts; set `false` to keep generation close to the literal prompt text

## Input Requirements

| Field                                             | Formats                              | Size    | Other                                                    |
| :------------------------------------------------ | :----------------------------------- | :------ | :------------------------------------------------------- |
| `first_frame` / `last_frame` / `reference_images` | JPEG, JPG, PNG (no alpha), BMP, WEBP | ≤ 20MB  | side 240–8000px, ratio ≤ 8:1                             |
| `reference_videos`                                | mp4, mov                             | ≤ 100MB | side 240–4096px, ratio ≤ 8:1, each 1–15s and ≤ 15s total |
| `reference_audios`                                | wav, mp3                             | ≤ 15MB  | each 1–15s and ≤ 15s total                               |


## OpenAPI

````yaml api-reference/endpoint/carrothub/berry-1.0/berry-1.0.yaml POST /vendors/carrothub/v1/berry-1.0/generation
openapi: 3.1.0
info:
  title: Berry1.0 Video Generation API
  description: >-
    Generate videos with the Berry1.0 all-in-one model (upstream Wan-3.0,
    CarrotHub / SmartStudio ecosystem).


    A single `generation` endpoint covers three capability sets — the media
    fields you send decide which one runs:


    - **Text-to-video**: `prompt` only, no media fields.

    - **Image-to-video (keyframe mode)**: `first_frame` and/or `last_frame`.

    - **Reference-to-video (reference mode)**: `reference_images` /
    `reference_videos` / `reference_audios` / `file` / `link`.


    Keyframe mode and reference mode are mutually exclusive — a single request
    cannot mix fields from both.


    In reference mode the `prompt` may refer to inputs by index ("Image 1" /
    "Video 1"),

    counted separately per field in array order.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.mulerouter.ai/
security:
  - bearerAuth: []
paths:
  /vendors/carrothub/v1/berry-1.0/generation:
    post:
      summary: Create Generation Task
      description: >-
        Create an asynchronous Berry1.0 video generation task.


        At least one of `prompt`, a keyframe field or a reference field must be
        provided.
      operationId: berry_1_0_generation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Berry10Request'
        required: true
      responses:
        '200':
          description: OK - Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
        '400':
          description: Bad Request - payload validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Berry10Request:
      type: object
      additionalProperties: false
      description: >-
        All-in-One video generation. At least one of `prompt`, a reference
        field, or a keyframe field

        must be provided.


        Two mutually exclusive input modes:

        - Reference mode: `reference_images` / `reference_videos` /
        `reference_audios` / `file` / `link`

        - Keyframe mode: `first_frame` / `last_frame`
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Text prompt describing the desired video. Up to 20000 characters —
            over-length prompts are

            **not rejected**, they are

            passed through and truncated upstream. Required unless a keyframe or
            reference input is given.
          default: null
        first_frame:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            First-frame image, strictly used as the first frame of the video.
            Accepts a public

            HTTP/HTTPS **URL**, a `data:image/<type>;base64,...` **data URI**,
            or a **bare Base64**

            string. Keyframe mode; cannot be combined with reference-mode
            fields.


            Upstream format requirements (validated upstream, not by this
            gateway):

            JPEG/JPG/PNG (no alpha)/BMP/WEBP, side 240–8000px, ratio ≤8:1,
            ≤20MB.
          default: null
        last_frame:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Last-frame image, strictly used as the last frame of the video. Same
            input formats and

            upstream constraints as `first_frame`. Keyframe mode; cannot be
            combined with

            reference-mode fields.
          default: null
        reference_images:
          anyOf:
            - type: array
              maxItems: 10
              items:
                type: string
            - type: 'null'
          description: >-
            Reference images, up to 10. Each item accepts a public HTTP/HTTPS
            **URL**, a

            `data:image/<type>;base64,...` **data URI**, or a **bare Base64**
            string; the three

            shapes may be mixed within one array. Referenced in `prompt` as
            "Image 1", "Image 2", …

            in array order. Reference mode; cannot be combined with keyframe
            fields.


            Upstream format requirements: JPEG/JPG/PNG (no alpha)/BMP/WEBP, side
            240–8000px,

            ratio ≤8:1, ≤20MB.
          default: null
        reference_videos:
          anyOf:
            - type: array
              maxItems: 5
              items:
                type: string
                format: uri
            - type: 'null'
          description: >-
            Reference videos, up to 5, total duration ≤15s. **URL only** —
            Base64 is not accepted

            here (a 100MB video would inflate the request body to ~133MB).
            Referenced in `prompt`

            as "Video 1", "Video 2", … in array order. Reference mode; cannot be
            combined with

            keyframe fields.


            Upstream format requirements: mp4/mov, side 240–4096px, ratio ≤8:1,
            each 1–15s, ≤100MB.

            This gateway checks only the recognizable file extension (`.mp4` /
            `.mov`);

            extensionless URLs such as signed links are passed through.
          default: null
        reference_audios:
          anyOf:
            - type: array
              maxItems: 5
              items:
                type: string
                format: uri
            - type: 'null'
          description: >-
            Reference audios, up to 5, total duration ≤15s. **URL only** —
            Base64 is not accepted here.

            Reference mode; cannot be combined with keyframe fields.


            Upstream format requirements: wav/mp3, each 1–15s, ≤15MB. This
            gateway checks only the

            recognizable file extension (`.wav` / `.mp3`); extensionless URLs
            are passed through.
          default: null
        file:
          anyOf:
            - type: string
              format: uri
              pattern: ^https?://
            - type: 'null'
          description: >-
            Reference file URL. HTTP/HTTPS only; at most one file. Supported
            formats: docx, doc, xlsx,

            xls, pptx, ppt, pdf, txt, key, pages, numbers, md. Maximum size is
            100MB. The upstream

            specification limits PDF, DOCX, DOC, PPTX, PPT, KEY, and PAGES files
            to 50 pages.

            Mutually exclusive with `link` and keyframe-mode fields.
          default: null
        link:
          anyOf:
            - type: string
              format: uri
              pattern: ^https?://
            - type: 'null'
          description: >-
            Public web page URL. HTTP/HTTPS only; the page must be accessible
            without authentication.

            At most one link. Mutually exclusive with `file` and keyframe-mode
            fields.
          default: null
        resolution:
          type: string
          description: >-
            Output resolution (case-insensitive). 2k / 4k require
            `berry-1.0-pro`.
          enum:
            - 480p
            - 720p
            - 1080p
          default: 1080p
        ratio:
          type: string
          description: >-
            Aspect ratio (case-insensitive). `adaptive` derives the ratio from
            intent and input media.
          enum:
            - '16:9'
            - '4:3'
            - '1:1'
            - '3:4'
            - '9:16'
            - adaptive
          default: adaptive
        duration:
          type: integer
          description: >-
            Video duration in seconds, 2–30 inclusive, or `-1` for smart
            duration

            (upstream picks the length from intent / content / media). With
            video input, the combined

            input + output duration must be ≤30s — validated upstream.
          default: 5
        audio:
          type: boolean
          description: >-
            Whether the output video includes an audio track. Pricing is
            identical either way.
          default: true
        seed:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 2147483647
            - type: 'null'
          description: >-
            Random seed [0, 2147483647]. null or omitted for an auto-generated
            seed.
          default: null
        prompt_extend:
          type: boolean
          description: >-
            Whether upstream rewrites (expands) the prompt before generation.
            Enabled by default:

            rewriting usually improves motion and cinematography on short
            prompts. Set to `false` to

            keep generation close to the literal prompt text.
          default: true
    TaskCreatedResponse:
      type: object
      additionalProperties: true
      properties:
        task_info:
          $ref: '#/components/schemas/TaskInfoCreated'
    ErrorResponse:
      type: object
      additionalProperties: true
      properties:
        task_info:
          $ref: '#/components/schemas/TaskInfoErrorResponse'
    TaskInfoCreated:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: UUID of the task
          format: uuid
        status:
          type: string
          description: Task status (pending when created)
          enum:
            - pending
        created_at:
          type: string
          description: Task creation timestamp (ISO 8601)
          format: date-time
        updated_at:
          type: string
          description: Task last update timestamp (ISO 8601)
          format: date-time
      required:
        - id
        - status
        - created_at
        - updated_at
    TaskInfoErrorResponse:
      type: object
      additionalProperties: true
      properties:
        id:
          type: string
          description: UUID of the task
          format: uuid
        status:
          type: string
          description: Task status (always failed for error responses)
          enum:
            - failed
        created_at:
          type: string
          description: Task creation timestamp (ISO 8601)
          format: date-time
        updated_at:
          type: string
          description: Task last update timestamp (ISO 8601)
          format: date-time
        error:
          $ref: '#/components/schemas/TaskInfoErrorObject'
      required:
        - id
        - status
        - created_at
        - updated_at
        - error
    TaskInfoErrorObject:
      type: object
      additionalProperties: true
      properties:
        code:
          type: integer
          description: MuleRouter Error code
          example: 2001
        title:
          type: string
          description: MuleRouter Error title
          example: Invalid Request
        detail:
          type: string
          description: MuleRouter Error detail
          example: >-
            cannot mix the reference mode (reference_images / reference_videos /
            reference_audios) with the keyframe mode (first_frame / last_frame)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````