### Install and authenticate the CLI

Source: https://docs.linkmodel.ai/cli

Install the CLI globally via npm and run the setup command to configure authentication.

```bash
npm install -g linkmodel-cli
lkm setup
```

--------------------------------

### Launch DeepSeek Harness Web UI

Source: https://docs.linkmodel.ai/agent-integrations-deepseek-harness

Starts the DeepSeek Harness Web UI using npx. Requires Node.js to be installed. The UI is served at http://127.0.0.1:3080 by default.

```bash
npx @deepseek-ai/dsh web
```

--------------------------------

### Start OpenCode

Source: https://docs.linkmodel.ai/agent-integrations-opencode

Launches OpenCode. After starting, use the /models command to select a linkmodel/* model.

```bash
opencode
```

--------------------------------

### Verify LinkModel CLI installation with version and help

Source: https://docs.linkmodel.ai/cli-installation

Checks that the CLI is installed and accessible by displaying its version and help information. Run these commands after installation to confirm the CLI is on your PATH.

```bash
lkm --version
lkm --help
```

--------------------------------

### Start Codex

Source: https://docs.linkmodel.ai/agent-integrations-codex

Launch the Codex application after configuration.

```bash
codex
```

--------------------------------

### Run interactive setup flow

Source: https://docs.linkmodel.ai/cli-authentication

Initiates the interactive configuration process for the CLI.

```bash
lkm setup
```

--------------------------------

### Use CLI in scripts with --json

Source: https://docs.linkmodel.ai/faq-cli

Use the --json flag to get JSON output for automation. The example shows image generation and video status commands with --wait.

```bash
lkm image "a product photo" --json
lkm video status <task_id> --wait --json
```

--------------------------------

### Image-to-video with first-frame-image

Source: https://docs.linkmodel.ai/cli-video-generation

Uses model-specific frame fields when supported. The example uses --first-frame-image with kling-v3.

```bash
lkm video gen "animate this product with a slow camera move" \
  -m kling-v3 \
  --first-frame-image https://example.com/first-frame.png
```

--------------------------------

### Install LinkModel CLI globally with npm

Source: https://docs.linkmodel.ai/cli-installation

Installs the LinkModel CLI package globally using npm. Run this command in your terminal to make the CLI available on your PATH.

```bash
npm install -g linkmodel-cli
```

--------------------------------

### Check Globally Installed CLI with npm install -g linkmodel-cli and lkm --version

Source: https://docs.linkmodel.ai/cli-troubleshooting

Run when the lkm command is not found. Installs the CLI globally via npm and verifies the installation. If lkm is still unavailable, check that the global npm bin directory is on the PATH.

```bash
npm install -g linkmodel-cli
lkm --version
```

--------------------------------

### Check installed LinkModel CLI version

Source: https://docs.linkmodel.ai/cli-installation

Displays the currently installed version of the LinkModel CLI. Use this after updating to confirm the new version.

```bash
lkm --version
```

--------------------------------

### OpenAPI specification for GET /files/{file_id}

Source: https://docs.linkmodel.ai/api-reference/gemini/get-gemini-file

Defines the GET /files/{file_id} endpoint for retrieving Gemini file status and URI. Requires a bearer token. Returns 200 with file details, 401 for invalid API key, and 404 for missing file.

```yaml
openapi: 3.0.3
info:
  title: Get Gemini file
  version: 1.0.0
  description: >-
    Read Gemini file-processing status and retrieve its native file URI when
    active.
servers:
  - url: https://api.linkmodel.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Gemini
  - name: files
paths:
  /files/{file_id}:
    get:
      tags:
        - Gemini
        - files
      summary: Get Gemini file
      description: >
        Poll this resource after completing an upload. Only an `active` file has
        a usable `uri` for Gemini-native `fileData.fileUri` input.


        The returned `gs://` URI is an account-scoped Gemini reference, not a
        public download URL or a cross-provider asset identifier.
      operationId: get-gemini-file
      parameters:
        - name: file_id
          in: path
          required: true
          description: File identifier returned when the upload session was created.
          schema:
            type: string
          example: file_example123
      responses:
        '200':
          description: Current Gemini file resource.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 0
                    example: 0
                  data:
                    type: object
                    required:
                      - file_id
                      - status
                    properties:
                      file_id:
                        type: string
                        example: file_example123
                      status:
                        type: string
                        description: >-
                          Common lifecycle values include `pending_upload`,
                          `transferring`, and `active`.
                        example: active
                      filename:
                        type: string
                        example: sample.mp4
                      mime_type:
                        type: string
                        example: video/mp4
                      bytes:
                        type: integer
                        format: int64
                        example: 35077
                      uri:
                        type: string
                        description: >-
                          Present when active. Pass unchanged as Gemini
                          `fileData.fileUri`.
                        example: >-
                          gs://managed-gemini-files/.../file_example123-sample.mp4
                      created_at:
                        type: integer
                        format: int64
                        example: 1783580035
                      expires_at:
                        type: integer
                        format: int64
                        example: 1783666435
        '401':
          description: Missing or invalid LinkModel API key.
        '404':
          description: File identifier not found or not accessible to this account.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

--------------------------------

### Configure Credentials Using LINKMODEL_API_KEY Environment Variable

Source: https://docs.linkmodel.ai/cli-troubleshooting

Alternative to lkm setup for configuring API key credentials. Use this to set the API key directly in the shell environment.

```bash
export LINKMODEL_API_KEY="<your-api-key>"
```

--------------------------------

### Active file resource JSON response

Source: https://docs.linkmodel.ai/gemini-video-understanding

Example of the JSON response received when a file is active, containing the required Gemini file URI.

```json
{
  "code": 0,
  "data": {
    "file_id": "file_example123",
    "status": "active",
    "filename": "sample.mp4",
    "mime_type": "video/mp4",
    "bytes": 35077,
    "uri": "gs://managed-gemini-files/.../file_example123-sample.mp4",
    "created_at": 1783580035,
    "expires_at": 1783666435
  }
}
```

--------------------------------

### POST /files/{file_id}/complete

Source: https://docs.linkmodel.ai/api-reference/gemini/complete-gemini-file-upload

Confirms that a Gemini file upload finished and starts server-side processing. Call this endpoint only after the direct PUT to the pre-signed upload URL succeeds. An accepted response starts file processing; poll the file resource until its status becomes 'active'.

```APIDOC
## POST /files/{file_id}/complete

### Description
Confirms that a Gemini file upload finished and starts server-side processing. Call this endpoint only after the direct PUT to the pre-signed upload URL succeeds. An accepted response starts file processing; poll the file resource until its status becomes `active`. This file lifecycle is only for Gemini-native `fileData` requests.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/files/{file_id}/complete

### Parameters
#### Path Parameters
- **file_id** (string) - Required - File identifier returned when the upload session was created.

### Response
#### Success Response (202)
Upload accepted and file processing started.

#### Error Responses
- **400** - The upload is incomplete or its metadata does not match the session.
- **401** - Missing or invalid LinkModel API key.
- **404** - File identifier not found or not accessible to this account.

### Security
Bearer authentication (JWT) required.
```

--------------------------------

### POST /videos/generations

Source: https://docs.linkmodel.ai/api-reference/bytedance/seedance-2-0-mini

Creates an asynchronous video generation task using the seedance-2-0-mini model. Supports text-to-video and image-to-video with optional reference media. Poll the returned task_id to get the result.

```APIDOC
## POST /videos/generations

### Description
Creates an asynchronous video generation task using the seedance-2-0-mini model. Supports text-to-video and image-to-video with optional reference media. Poll the returned task_id to get the result.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/videos/generations

### Parameters
#### Request Body
- **prompt** (string) - Required for text-to-video; optional for image-to-video. Max length: 5000.
- **first_frame_image** (string, url) - Optional image-to-video start frame; cannot be combined with reference images, videos or audios.
- **last_frame_image** (string, url) - Optional end frame; requires first_frame_image and cannot be combined with reference media.
- **images** (array of string, url) - Up to 9 reference image URLs; cannot be combined with first or last frame.
- **videos** (array of string, url) - Up to 3 reference video URLs; cannot be combined with first or last frame.
- **audios** (array of string, url) - Up to 3 reference audio URLs; requires at least one reference image or video and cannot be combined with first/last frame.
- **resolution** (string) - Must be one of: 480P, 720P. Defaults to `720P`.
- **duration** (integer) - 4-15 seconds; -1 means intelligent duration. Defaults to `5`.

### Request Example
{
  "prompt": "A cat playing in the garden",
  "resolution": "720P",
  "duration": 5
}

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the created task. Use it to poll the task status.

#### Response Example
{
  "task_id": "your-task-id"
}

### Notes
- This endpoint creates an asynchronous task. Poll `GET /videos/generations/{task_id}` with the returned `task_id` until the task reaches a terminal state.
- If the POST request times out or its result is uncertain, do not blindly retry it. The original request may already have created another task and billing order.
- Completed asset URLs are dynamically signed. Download or copy assets that must be retained instead of treating the URLs as permanent identifiers.
```

--------------------------------

### Check Authentication Status with lkm auth status

Source: https://docs.linkmodel.ai/cli-troubleshooting

Run to verify whether the CLI is authenticated. If it fails or shows no key, proceed with credential configuration using lkm setup or the LINKMODEL_API_KEY environment variable.

```bash
lkm auth status
```

--------------------------------

### POST /images/generations

Source: https://docs.linkmodel.ai/api-reference/google/gemini-31-flash-image

Creates an asynchronous image generation task using the gemini-3.1-flash-image model. Accepts a prompt and optional reference images, quality, and size parameters. Returns a task_id that can be polled via GET /images/generations/{task_id} until completion.

```APIDOC
## POST /images/generations

### Description
Creates an asynchronous image generation task using the gemini-3.1-flash-image model. Accepts a prompt and optional reference images, quality, and size parameters. Returns a task_id that can be polled via GET /images/generations/{task_id} until completion.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/images/generations

### Parameters
#### Request Body
- **model** (string) - Required - Must be one of: gemini-3.1-flash-image.
- **images** (array of url strings) - Optional - Up to 10 reference images.
- **quality** (string) - Optional - Must be one of: 0.5K, 1K, 2K, 4K. Defaults to `1K`.
- **prompt** (string) - Required - Length must be at least 1.
- **size** (string) - Optional - Must be one of: 16:9, 16x9, 1:1, 1x1, 21:9, 21x9, 2:3, 2x3, 3:2, 3:4, 3x2, 3x4, 4:3, 4:5, 4x3, 4x5, 5:4, 5x4, 9:16, 9x16.

### Request Example
{
  "model": "gemini-3.1-flash-image",
  "prompt": "A beautiful sunset over the ocean",
  "images": ["https://example.com/image1.jpg"],
  "quality": "1K",
  "size": "1:1"
}

### Response
#### Success Response (200)
Business response. `code=0` means the task was accepted; validation failures can return HTTP 200 with `code=400`.

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "string"
  },
  "msg": "success"
}
```

--------------------------------

### OpenAPI specification for MiniMax-H3 video generation

Source: https://docs.linkmodel.ai/api-reference/minimax/minimax-h3

YAML OpenAPI 3.0.3 specification for the POST /videos/generations endpoint. It defines the request body schema, including prompt, first_frame_image, last_frame_image, images, videos, audio_url, audios, duration, resolution, size, and model parameters. The endpoint creates an asynchronous task; poll GET /videos/generations/{task_id} with the returned task_id until terminal state. Do not blindly retry on timeout, and treat asset URLs as dynamically signed.

```yaml
openapi: 3.0.3
info:
  title: MiniMax-H3
  version: 1.0.0
  description: >-
    MiniMax's omni-modal audio-video generation system unifies text, image,
    video, and audio context to create videos up to 15 seconds at 2K with native
    stereo sound for advertising, e-commerce, and film production.
  x-linkmodel-sort-weight: 99202607319
servers:
  - url: https://api.linkmodel.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: MiniMax
  - name: video
paths:
  /videos/generations:
    post:
      tags:
        - MiniMax
        - video
      summary: MiniMax-H3
      description: >
        MiniMax's omni-modal audio-video generation system unifies text, image,
        video, and audio context to create videos up to 15 seconds at 2K with
        native stereo sound for advertising, e-commerce, and film production.


        |   |   |

        | --- | --- |

        | **Provider** | MiniMax |

        | **Tasks** | text-to-video · image-to-video |

        | **Starting from** | 0.000000 USD / call · <a
        href="https://linkmodel.ai/en/models/MiniMax-H3" target="_blank"
        rel="noopener">Pricing details</a> |


        ## Task lifecycle


        This endpoint creates an asynchronous task. Poll `GET
        /videos/generations/{task_id}` with the returned `task_id` until the
        task reaches a terminal state.


        If the POST request times out or its result is uncertain, do not blindly
        retry it. The original request may already have created another task and
        billing order.


        Completed asset URLs are dynamically signed. Download or copy assets
        that must be retained instead of treating the URLs as permanent
        identifiers.
      operationId: minimax-h3
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  description: Length must be at least 1.
                first_frame_image:
                  type: string
                  format: url
                  description: Cannot be mixed with reference image, video or audio inputs.
                last_frame_image:
                  type: string
                  format: url
                  description: >-
                    Optional; cannot be mixed with reference image, video or
                    audio inputs.
                images:
                  type: array
                  maxItems: 9
                  items:
                    type: string
                    format: url
                  description: Up to 9 images; cannot be mixed with first/last frame mode.
                videos:
                  type: array
                  maxItems: 3
                  items:
                    type: string
                    format: url
                  description: Up to 3 videos.
                audio_url:
                  type: string
                  format: url
                  description: >-
                    Reference audio requires at least one reference image or
                    video.
                audios:
                  type: array
                  maxItems: 3
                  items:
                    type: string
                    format: url
                  description: >-
                    Up to 3 audio inputs in total; reference audio requires an
                    image or video.
                duration:
                  type: integer
                  default: 5
                  minimum: 4
                  maximum: 15
                  description: 4 to 15 seconds. Defaults to `5`. Value is in s.
                resolution:
                  type: string
                  enum:
                    - 2K
                    - 768P
                  default: 768P
                  description: 'Must be one of: 2K, 768P. Defaults to `768P`.'
                size:
                  type: string
                  enum:
                    - 16x9
                    - 1x1
                    - 21x9
                    - 3x4
                    - 4x3
                    - 9x16
                    - adaptive
                  default: 16x9
                  description: >-
                    Text-to-video requires a fixed ratio; adaptive is for
                    requests with visual input. Defaults to `16x9`.
                model:

```

--------------------------------

### OpenAPI specification for gemini-3.1-flash-image POST /images/generations

Source: https://docs.linkmodel.ai/api-reference/google/gemini-31-flash-image

OpenAPI 3.0.3 specification for the gemini-3.1-flash-image image generation endpoint. The endpoint creates an asynchronous task; poll GET /images/generations/{task_id} with the returned task_id until a terminal state. If the POST request times out, do not blindly retry as it may create another task and billing order. Completed asset URLs are dynamically signed and should be downloaded or copied if retention is needed.

```yaml
openapi: 3.0.3
info:
  title: gemini-3.1-flash-image
  version: 1.0.0
  description: >-
    Nano Banana (gemini-3.1-flash-image) is a highly multifunctional generative
    model designed for speed, accuracy, and creative flexibility. It excels at
    transforming text prompts into stunning visual effects while providing
    advanced composition and style transfer capabilities.
  x-linkmodel-sort-weight: 99202605289
servers:
  - url: https://api.linkmodel.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Google
  - name: image
paths:
  /images/generations:
    post:
      tags:
        - Google
        - image
      summary: gemini-3.1-flash-image
      description: >
        Nano Banana (gemini-3.1-flash-image) is a highly multifunctional
        generative model designed for speed, accuracy, and creative flexibility.
        It excels at transforming text prompts into stunning visual effects
        while providing advanced composition and style transfer capabilities.


        |   |   |

        | --- | --- |

        | **Provider** | Google |

        | **Tasks** | text-to-image · image-to-image |

        | **Starting from** | 0.033750 USD / call · <a
        href="https://linkmodel.ai/en/models/gemini-3.1-flash-image"
        target="_blank" rel="noopener">Pricing details</a> |


        ## Task lifecycle


        This endpoint creates an asynchronous task. Poll `GET
        /images/generations/{task_id}` with the returned `task_id` until the
        task reaches a terminal state.


        If the POST request times out or its result is uncertain, do not blindly
        retry it. The original request may already have created another task and
        billing order.


        Completed asset URLs are dynamically signed. Download or copy assets
        that must be retained instead of treating the URLs as permanent
        identifiers.
      operationId: gemini-3-1-flash-image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  enum:
                    - gemini-3.1-flash-image
                  description: 'Must be one of: gemini-3.1-flash-image.'
                images:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: url
                  description: Up to 10 reference images.
                quality:
                  type: string
                  enum:
                    - 0.5K
                    - 1K
                    - 2K
                    - 4K
                  default: 1K
                  description: 'Must be one of: 0.5K, 1K, 2K, 4K. Defaults to `1K`.'
                prompt:
                  type: string
                  minLength: 1
                  description: Length must be at least 1.
                size:
                  type: string
                  enum:
                    - '16:9'
                    - 16x9
                    - '1:1'
                    - 1x1
                    - '21:9'
                    - 21x9
                    - '2:3'
                    - 2x3
                    - '3:2'
                    - 3:4
                    - 3x2
                    - 3x4
                    - '4:3'
                    - '4:5'
                    - 4x3
                    - 4x5
                    - '5:4'
                    - 5x4
                    - '9:16'
                    - 9x16
                  description: >-
                    Must be one of: 16:9, 16x9, 1:1, 1x1, 21:9, 21x9, 2:3, 2x3,
                    3:2, 3:4, 3x2, 3x4, 4:3, 4:5, 4x3, 4x5, 5:4, 5x4, 9:16,
                    9x16.
              required:
                - model
                - prompt
      responses:
        '200':
          description: >-
            Business response. `code=0` means the task was accepted; validation
            failures can return HTTP 200 with `code=400`.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - code
                      - data
                      - msg
                    properties:
                      code:
                        type: integer
```

--------------------------------

### List available models with lkm models list

Source: https://docs.linkmodel.ai/cli-model-schemas

Use these commands to list all available models or filter them by modality.

```bash
lkm models list
lkm models list --modality image
lkm models list --modality video
```

--------------------------------

### Configure API key directly

Source: https://docs.linkmodel.ai/cli-authentication

Sets the API key manually and verifies the authentication status.

```bash
lkm auth login --api-key <your-api-key>
lkm auth status
```

--------------------------------

### GET /query/video-generation

Source: https://docs.linkmodel.ai/api-reference/legacy/video-task-query

Retrieves the current status and result of a video generation task using the task_id returned from either video creation endpoint. This is a legacy endpoint; new integrations should use GET /v1/videos/generations/{task_id}.

```APIDOC
## GET /query/video-generation

### Description
Retrieves the current status and result of a video generation task using the task_id returned from either video creation endpoint. This is a legacy endpoint; new integrations should use GET /v1/videos/generations/{task_id}.

### Method
GET

### Endpoint
/query/video-generation

### Parameters
#### Query Parameters
- **task_id** (string) - Required - Task id returned from either video creation endpoint.

### Response
#### Success Response (200)
- **code** (integer) - Example: 0
- **data** (object) - Contains task details.
  - **task_id** (string) - The task identifier.
  - **status** (string) - Status of the task. Possible values: Pending, Processing, Success, Failed, Cancelled.
  - **file_url** (string, uri) - Transient signed URL to the result file. Should not be used as a permanent identifier.
- **message** (string) - Example: success

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "aurora_abc123",
    "status": "Success",
    "file_url": "https://example.com/video.mp4"
  },
  "message": "success"
}

#### Error Responses
- **401** - Unauthorized — missing or invalid API key.
- **404** - Task not found.

### Authentication
Bearer token (JWT) required.
```

--------------------------------

### Select a model with -m and model-specific options

Source: https://docs.linkmodel.ai/cli-video-generation

Uses -m or --model to select a model. Model-specific options like --duration, --resolution, --size, and --extends-cfg-scale are generated from bundled LinkModel schemas.

```bash
lkm video gen "a cinematic product orbit" \
  -m kling-v3 \
  --duration 5 \
  --resolution 720P \
  --size 16x9 \
  --extends-cfg-scale 0.7
```

--------------------------------

### Verify CLI version and model list

Source: https://docs.linkmodel.ai/cli-model-schemas

Check the current CLI version and list models to verify updates.

```bash
lkm --version
lkm models list
```

--------------------------------

### Generate a video

Source: https://docs.linkmodel.ai/cli

Use the lkm video command followed by a prompt to generate a video.

```bash
lkm video "a cinematic product orbit"
```

--------------------------------

### Inspect Model with lkm models show <model>

Source: https://docs.linkmodel.ai/cli-troubleshooting

Run before using provider-specific options to see the bundled schema for the selected model. This helps identify valid flags and parameters.

```bash
lkm models show <model>
```

--------------------------------

### GET /api/v1/tasks/{task_id}

Source: https://docs.linkmodel.ai/api-reference/bytedance/seedream-40

Polls the status of an image generation task using its task_id.

```APIDOC
## GET /api/v1/tasks/{task_id}

### Description
Polls the status of a previously created image generation task.

### Method
GET

### Endpoint
/api/v1/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The task ID returned from task creation.

### Response
#### Success Response (200)
- **code** (integer) - Status code, 0 for success.
- **data** (object) - Response data.
  - **task_id** (string) - Task ID.
  - **order_id** (string) - Billing order ID.
  - **status** (string) - Task status.
  - **price** (number) - Charged amount.
- **msg** (string) - Response message.
- **request_id** (string, uuid) - Request identifier.

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "aurora_abc123",
    "order_id": "019da9cf-d1db-78e1-ac23-526774d01193",
    "status": "Processing",
    "price": 0.074
  },
  "msg": "success",
  "request_id": "250b66dd-e1fb-4bb6-b5f6-c668efadc35d"
}

#### Error Response (400)
- **code** (integer) - Error code, 400.
- **msg** (string) - Error message.
- **request_id** (string, uuid) - Request identifier.

#### Error Response Example
{
  "code": 400,
  "msg": "task_id is required",
  "request_id": "96be7a7d-3e81-4916-a6b8-19b32773a693"
}

#### Error Response (401)
- **code** (integer) - Error code, 401.
- **data** (object) - Empty object.
- **msg** (string) - Error message.
- **request_id** (string, uuid) - Request identifier.

#### Error Response Example
{
  "code": 401,
  "data": {},
  "msg": "invalid api key",
  "request_id": "bff4c295-c7da-4507-9708-4627cb6373ba"
}

#### Error Response (500)
- **code** (integer) - Error code, 500.
- **msg** (string) - Error message.
- **request_id** (string, uuid) - Request identifier.

#### Error Response Example
{
  "code": 500,
  "msg": "create task failed: billing: code=100601: insufficient balance",
  "request_id": "3409f6fb-fa9a-4534-b530-195b5f6f4e32"
}
```

--------------------------------

### Configure Codex Desktop API Key

Source: https://docs.linkmodel.ai/agent-integrations-troubleshooting

Set the API key in the .env file for Codex desktop applications and restart the app.

```text
LINKMODEL_API_KEY=<YOUR_API_KEY>
```

--------------------------------

### Gemini API response format

Source: https://docs.linkmodel.ai/gemini-video-understanding

Example of the native JSON response returned by the Gemini model.

```json
{
  \"candidates\": [
    {
      \"content\": {
        \"parts\": [{ \"text\": \"The video shows...\" }],
        \"role\": \"model\"
      },
      \"finishReason\": \"STOP\"
    }
  ],
  \"modelVersion\": \"gemini-3.1-flash-lite\",
  \"usageMetadata\": {
    \"promptTokenCount\": 140,
    \"candidatesTokenCount\": 183,
    \"totalTokenCount\": 323
  }
}
```

--------------------------------

### POST /videos/generations

Source: https://docs.linkmodel.ai/api-reference/minimax/minimax-hailuo-23

Creates an asynchronous video generation task using the MiniMax-Hailuo-2.3 model. Supports text-to-video and image-to-video tasks with configurable duration and resolution.

```APIDOC
## POST /videos/generations

### Description
Creates an asynchronous video generation task using the MiniMax-Hailuo-2.3 model. Supports text-to-video and image-to-video tasks with configurable duration and resolution.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - Must be one of: MiniMax-Hailuo-2.3.
- **prompt** (string) - Required - Length must be between 1 and 2000.
- **duration** (integer) - Optional - Must be one of: 6, 10. Defaults to `6`. Value is in s. Conditional limits: 1080P resolution only supports 6 seconds duration.
- **first_frame_image** (string, url) - Optional - URL of the first frame image for image-to-video tasks.
- **resolution** (string) - Optional - Must be one of: 1080P, 768P. Defaults to `768P`.

### Request Example
{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "A cinematic shot of a robot walking through a futuristic city",
  "duration": 6,
  "first_frame_image": "https://example.com/first-frame.jpg",
  "resolution": "768P"
}

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the created task. Use this to poll the task status.

#### Response Example
{
  "task_id": "your-task-id"
}

### Task Lifecycle
This endpoint creates an asynchronous task. Poll `GET /videos/generations/{task_id}` with the returned `task_id` until the task reaches a terminal state.

If the POST request times out or its result is uncertain, do not blindly retry it. The original request may already have created another task and billing order.

Completed asset URLs are dynamically signed. Download or copy assets that must be retained instead of treating the URLs as permanent identifiers.

### Authentication
Requires bearer token authentication.
```

--------------------------------

### Create a video generation task with curl

Source: https://docs.linkmodel.ai/first-api-call

POST to /videos/generations to create a video task. The response includes a task_id. If the request times out or is uncertain, do not blindly retry to avoid duplicate tasks and billing.

```bash
curl --request POST \
  --url https://api.linkmodel.ai/v1/videos/generations \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "sora-2",
    "prompt": "A golden retriever catching a frisbee in slow motion"
  }'
```

--------------------------------

### OpenAPI definition for List models

Source: https://docs.linkmodel.ai/api-reference/models/list-models

The OpenAPI specification for the /models GET endpoint, defining the response structure and metadata.

```yaml
openapi: 3.0.3
info:
  title: List available models
  version: 1.0.0
  description: Return the model catalog currently visible through LinkModel.
servers:
  - url: https://api.linkmodel.ai/v1
    description: Production
security: []
tags:
  - name: models
paths:
  /models:
    get:
      tags:
        - models
      summary: List models
      description: >
        Return the model catalog currently visible through LinkModel in an
        OpenAI-compatible list envelope.


        This endpoint is public and does not require a Bearer API key.


        Catalog visibility does not guarantee that every parameter combination
        has a billable SKU. Open the model's API Reference page for its
        supported request schema and current pricing.


        A `created` value of `0` means the upstream model metadata does not
        provide a creation timestamp.
      operationId: list-models
      responses:
        '200':
          description: Current visible model list.
          content:
            application/json:
              schema:
                type: object
                required:
                  - object
                  - data
                properties:
                  object:
                    type: string
                    enum:
                      - list
                    example: list
                  data:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - object
                        - created
                        - owned_by
                      properties:
                        id:
                          type: string
                          example: seedream-4.0
                        object:
                          type: string
                          enum:
                            - model
                          example: model
                        created:
                          type: integer
                          format: int64
                          description: >-
                            Unix timestamp. `0` is used when upstream creation
                            metadata is unavailable.
                          example: 0
                        owned_by:
                          type: string
                          example: Bytedance
      security: []
```

--------------------------------

### Update LinkModel CLI to latest version

Source: https://docs.linkmodel.ai/cli-installation

Updates the globally installed LinkModel CLI package to the latest version using npm.

```bash
npm install -g linkmodel-cli@latest
```

--------------------------------

### POST /videos/generations

Source: https://docs.linkmodel.ai/api-reference/minimax/minimax-hailuo-02

Creates an asynchronous video generation task using the MiniMax-Hailuo-02 model. Supports text-to-video and image-to-video generation with configurable duration and resolution.

```APIDOC
## POST /videos/generations

### Description
Creates an asynchronous video generation task using the MiniMax-Hailuo-02 model. Supports text-to-video and image-to-video generation with configurable duration and resolution.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/videos/generations

### Parameters
#### Request Body
- **model** (string) - Required - Must be one of: MiniMax-Hailuo-02.
- **prompt** (string) - Required - Length must be between 1 and 2000.
- **first_frame_image** (string, url) - Optional - URL of the first frame image for image-to-video generation.
- **last_frame_image** (string, url) - Optional - URL of the last frame image for image-to-video generation.
- **duration** (integer) - Optional - Must be one of: 6, 10. Defaults to `6`. Value is in seconds. Conditional limits: 1080P resolution only supports 6 seconds duration.
- **resolution** (string) - Optional - Must be one of: 1080P, 512P, 768P. Defaults to `768P`.

### Request Example
{
  "model": "MiniMax-Hailuo-02",
  "prompt": "A cinematic shot of a futuristic city",
  "duration": 6,
  "resolution": "768P"
}

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the created task, used for polling the task status.

#### Response Example
{
  "task_id": "your-task-id"
}

### Notes
- This endpoint creates an asynchronous task. Poll `GET /videos/generations/{task_id}` with the returned `task_id` until the task reaches a terminal state.
- If the POST request times out or its result is uncertain, do not blindly retry it. The original request may already have created another task and billing order.
- Completed asset URLs are dynamically signed. Download or copy assets that must be retained instead of treating the URLs as permanent identifiers.
```

--------------------------------

### OpenAPI definition for GET /query/video-generation

Source: https://docs.linkmodel.ai/api-reference/legacy/video-task-query

The OpenAPI specification for the legacy video task query endpoint, including security schemes and response models.

```yaml
openapi: 3.0.3
info:
  title: Video task query
  version: 1.0.0
  description: Historical video task query endpoint retained for existing integrations.
servers:
  - url: https://api.linkmodel.ai/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: legacy
paths:
  /query/video-generation:
    get:
      tags:
        - legacy
      summary: Video task query
      description: >
        This historical query endpoint remains supported. New integrations
        should use `GET /v1/videos/generations/{task_id}`.


        Both query routes can retrieve tasks created through either the primary
        or historical video creation endpoint. The signed `file_url` is
        transient and should not be used as a permanent identifier.
      operationId: legacy-query-video-generation
      parameters:
        - name: task_id
          in: query
          required: true
          description: Task id returned from either video creation endpoint.
          schema:
            type: string
            example: aurora_abc123
      responses:
        '200':
          description: Current video task status and result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 0
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                      status:
                        type: string
                        enum:
                          - Pending
                          - Processing
                          - Success
                          - Failed
                          - Cancelled
                      file_url:
                        type: string
                        format: uri
                  message:
                    type: string
                    example: success
        '401':
          description: Unauthorized — missing or invalid API key.
        '404':
          description: Task not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
```

--------------------------------

### POST /v1/video_generation

Source: https://docs.linkmodel.ai/api-reference/minimax/minimax-hailuo-23

Creates a video generation task using the Hailuo 2.3 model. Accepts prompt and optional parameters, returns a task ID for polling.

```APIDOC
## POST /v1/video_generation

### Description
Creates a video generation task using the Hailuo 2.3 model. Accepts prompt and optional parameters, returns a task ID for polling.

### Method
POST

### Endpoint
/v1/video_generation

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier, e.g., "MiniMax-Hailuo-2.3".
- **prompt** (string) - Required - Text description of the video to generate.
- **resolution** (string) - Optional - Output resolution, e.g., "768p" or "1080p".
- **duration** (integer) - Optional - Duration in seconds. Conditional limit: 10 seconds duration only supports 768P resolution.

### Request Example
{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "A cat playing in a garden",
  "resolution": "768p",
  "duration": 10
}

### Response
#### Success Response (200)
- **code** (integer) - 0 indicates success.
- **data.task_id** (string) - Use this id to poll task status.
- **data.order_id** (string) - Billing order id.
- **data.status** (string) - Task status, e.g., "Processing".
- **data.price** (number) - Charged amount in the model's pricing currency.
- **msg** (string) - Success message.
- **request_id** (string) - UUID for request tracking.

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "aurora_abc123",
    "order_id": "019da9cf-d1db-78e1-ac23-526774d01193",
    "status": "Processing",
    "price": 0.074
  },
  "msg": "success",
  "request_id": "250b66dd-e1fb-4bb6-b5f6-c668efadc35d"
}

#### Error Responses
- **400 Bad Request** - Malformed HTTP request rejected by the Gateway. Model and parameter validation may instead use HTTP 200 with business code=400.
- **401 Unauthorized** - Missing or invalid API key.
- **500 Internal Error** - Task creation failed (e.g. insufficient balance).

#### Error Response Example (Business Validation)
{
  "code": 400,
  "data": {},
  "msg": "model is required",
  "request_id": "96be7a7d-3e81-4916-a6b8-19b32773a693"
}

#### Error Response Example (Gateway)
{
  "code": 400,
  "msg": "task_id is required",
  "request_id": "96be7a7d-3e81-4916-a6b8-19b32773a693"
}

#### Error Response Example (Unauthorized)
{
  "code": 401,
  "data": {},
  "msg": "invalid api key",
  "request_id": "bff4c295-c7da-4507-9708-4627cb6373ba"
}

#### Error Response Example (Internal)
{
  "code": 500,
  "msg": "create task failed: billing: code=100601: insufficient balance",
  "request_id": "3409f6fb-fa9a-4534-b530-195b5f6f4e32"
}

### Authentication
Bearer token (JWT) required. Use the Authorization header: `Authorization: Bearer <token>`.
```

--------------------------------

### GET /videos/generations/{task_id}

Source: https://docs.linkmodel.ai/api-reference/openai/sora-2

Polls the status of an asynchronous video generation task until it reaches a terminal state. Use the task_id returned from the POST request.

```APIDOC
## GET /videos/generations/{task_id}

### Description
Polls the status of an asynchronous video generation task until it reaches a terminal state. Use the task_id returned from the POST request.

### Method
GET

### Endpoint
https://api.linkmodel.ai/v1/videos/generations/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The task identifier returned from the POST /videos/generations request.

### Response
#### Success Response (200)
Returns the current status of the video generation task.

#### Response Example
{
  "code": 0,
  "data": {
    "task_id": "string",
    "status": "completed",
    "assets": [
      {
        "url": "https://signed-url.example.com/video.mp4"
      }
    ]
  },
  "msg": "success"
}
```

--------------------------------

### GET /models

Source: https://docs.linkmodel.ai/api-reference/models/list-models

Returns the model catalog currently visible through LinkModel in an OpenAI-compatible list envelope. This endpoint is public and does not require a Bearer API key.

```APIDOC
## GET /models

### Description
Return the model catalog currently visible through LinkModel in an OpenAI-compatible list envelope. This endpoint is public and does not require a Bearer API key.

### Method
GET

### Endpoint
https://api.linkmodel.ai/v1/models

### Parameters
None

### Response
#### Success Response (200)
- **object** (string) - Always 'list'.
- **data** (array) - Array of model objects.
  - **id** (string) - Model identifier, e.g., 'seedream-4.0'.
  - **object** (string) - Always 'model'.
  - **created** (integer) - Unix timestamp. 0 is used when upstream creation metadata is unavailable.
  - **owned_by** (string) - Owner of the model, e.g., 'Bytedance'.

#### Response Example
{
  "object": "list",
  "data": [
    {
      "id": "seedream-4.0",
      "object": "model",
      "created": 0,
      "owned_by": "Bytedance"
    }
  ]
}
```

--------------------------------

### POST /files/upload-sessions

Source: https://docs.linkmodel.ai/api-reference/gemini/create-gemini-upload-session

Creates a short-lived upload instruction for a local file. The response contains a pre-signed URL, method, and headers for direct file upload, after which the upload is completed through LinkModel.

```APIDOC
## POST /files/upload-sessions

### Description
Create a short-lived upload instruction for a local file. Send the file bytes directly to the returned `upload.url`, using the returned method and headers, then complete the upload through LinkModel.

### Method
POST

### Endpoint
https://api.linkmodel.ai/v1/files/upload-sessions

### Parameters
#### Request Body
No request body parameters are documented.

### Request Example
No request example is provided.

### Response
#### Success Response (200)
No response fields are documented.

#### Response Example
No response example is provided.

### Error Handling
No error responses are documented.
```

--------------------------------

### Generate an image

Source: https://docs.linkmodel.ai/cli

Use the lkm image command followed by a prompt to generate an image.

```bash
lkm image "a product photo on a clean studio background"
```