ViewMax

https://viewmax.studio/docs
Admin
ViewMax is a creative media generation platform providing a REST API, MCP server, CLI, and agent...
Tokens:11,724
Snippets:130
Trust Score:6.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install ViewMax CLI

Source: https://viewmax.studio/docs/cli

Commands to navigate to the package directory and link the CLI for global usage.

```bash
cd packages/viewmax-cli
node bin/viewmax.mjs models
npm link
viewmax models
```

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

### Generate video with cURL

Source: https://viewmax.studio/docs/api/models/kling-2-6

Example request for the kling-2-6 model using the text-to-video mode.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2-6",
    "mode": "text-to-video",
    "prompt": "A slow dolly through a neon-lit night market",
    "options": { "duration": "5s", "audio": true }
  }'
```

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

### Install Additional Media Generation Skills

Source: https://viewmax.studio/docs/skills

Downloads the skill definition and API reference files for image, music, and audio generation capabilities.

```bash
# Image (text-to-image and image-to-image)
curl -fsSL https://viewmax.studio/skills/viewmax-image/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-image/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-image/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-image/reference.md

# Music
curl -fsSL https://viewmax.studio/skills/viewmax-music/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-music/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-music/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-music/reference.md

# Audio (text-to-speech and sound effects)
curl -fsSL https://viewmax.studio/skills/viewmax-audio/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-audio/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-audio/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-audio/reference.md
```

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

### Install ViewMax Video Generation Skill

Source: https://viewmax.studio/docs/skills

Downloads the skill definition and API reference files to the local Claude skills directory.

```bash
curl -fsSL https://viewmax.studio/skills/viewmax-video/SKILL.md \
  --create-dirs -o ~/.claude/skills/viewmax-video/SKILL.md
curl -fsSL https://viewmax.studio/skills/viewmax-video/reference.md \
  --create-dirs -o ~/.claude/skills/viewmax-video/reference.md
```

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

### Generate Video Command

Source: https://viewmax.studio/docs/cli

Example of a video generation request with specific model, prompt, and output parameters.

```bash
viewmax generate -m sora-2 -p "A paper kite crossing a bright summer sky" \
  --duration 8s --resolution 720p --aspect-ratio 16:9 --wait --output kite.mp4
```

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

### Create an image task with cURL

Source: https://viewmax.studio/docs/api/image-generation

Example request for generating an image using the POST endpoint.

```bash
curl -X POST https://viewmax.studio/api/v1/images \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "scene": "text-to-image",
    "prompt": "A paper kite crossing a bright summer sky",
    "options": { "aspect_ratio": "16:9", "quality": "2K" }
  }'
```

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

### Generate Music with cURL

Source: https://viewmax.studio/docs/api/music-generation

Example of initiating a music generation task using a cURL command with a JSON payload.

```bash
curl -X POST https://viewmax.studio/api/v1/music \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Warm lo-fi hip-hop with a mellow piano loop",
    "options": { "duration_seconds": 30, "instrumental": true }
  }'
```

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

### Generate Video via cURL

Source: https://viewmax.studio/docs/api/models/seedance

Example request for generating a video using the Seedance 2 Mini model via the ViewMax REST API.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-mini",
    "mode": "text-to-video",
    "prompt": "Ink clouds blooming in clear water",
    "options": {
      "duration": "4s",
      "resolution": "480p",
      "aspect_ratio": "1:1",
      "audio": true
    }
  }'
```

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

### GET /api/v1/models

Source: https://viewmax.studio/docs/api

Retrieves the model catalog and pricing information.

```APIDOC
## GET /api/v1/models

### Description
Retrieves the model catalog and pricing information. Supports filtering by media type.

### Method
GET

### Endpoint
/api/v1/models

### Parameters
#### Query Parameters
- **type** (string) - Optional - The media type to filter by: 'video' (default), 'image', or 'music'.
```

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

### GET /api/v1/credits

Source: https://viewmax.studio/docs/api

Reads the remaining account credits.

```APIDOC
## GET /api/v1/credits

### Description
Retrieves the current balance of remaining credits for the authenticated account.

### Method
GET

### Endpoint
/api/v1/credits
```

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

### Authenticate API Request with cURL

Source: https://viewmax.studio/docs/api/authentication

Example of using the API key with a cURL request to the credits endpoint.

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/credits
```

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

### GET /api/v1/credits

Source: https://viewmax.studio/docs/api/authentication

Retrieve credit information for the authenticated user.

```APIDOC
## GET /api/v1/credits

### Description
Retrieves the current credit balance for the authenticated account.

### Method
GET

### Endpoint
/api/v1/credits
```

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

### GET /api/v1/voices

Source: https://viewmax.studio/docs/api

Retrieves the text-to-speech voice catalog.

```APIDOC
## GET /api/v1/voices

### Description
Retrieves the available text-to-speech voice catalog.

### Method
GET

### Endpoint
/api/v1/voices
```

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

### Successful API response structure

Source: https://viewmax.studio/docs/api/audio-generation

Example of a successful JSON response containing the task ID, status, credit cost, and audio URLs.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "success",
    "costCredits": 1,
    "taskUrls": ["https://.../audio.mp3"]
  }
}
```

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

### GET https://viewmax.studio/api/v1/tasks/{taskId}

Source: https://viewmax.studio/docs/api/tasks

Retrieves the status and task record for a specific video generation task.

```APIDOC
## GET https://viewmax.studio/api/v1/tasks/{taskId}

### Description
Retrieves the public task record for a given task ID, including the status and generated video URLs.

### Method
GET

### Endpoint
https://viewmax.studio/api/v1/tasks/{taskId}

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task returned by the video creation endpoint.

### Response
#### Success Response (200)
- **code** (integer) - Status code of the response.
- **message** (string) - Descriptive message.
- **data** (object) - The task record containing status and taskUrls.

#### Error Handling
- **404** - Returned if the task does not exist or is not owned by the authenticated user (code: -1, message: "task not found").
```

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

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

Source: https://viewmax.studio/docs/api/authentication

Retrieve the status or details of a specific task.

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

### Description
Retrieves details for a specific task.

### Method
GET

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

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task.
```

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

### GET /api/v1/models

Source: https://viewmax.studio/docs/api/models

Retrieves the current catalog of video models, including supported modes and credit pricing metadata.

```APIDOC
## GET /api/v1/models

### Description
Fetches the machine-readable source of truth for live video model capabilities and pricing metadata. This endpoint should be called before submitting any billable requests.

### Method
GET

### Endpoint
/api/v1/models
```

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

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

Source: https://viewmax.studio/docs/api

Reads the status and result URLs of a specific task.

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

### Description
Reads the current status and result URLs for a given task ID. Used for polling asynchronous tasks.

### Method
GET

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

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task.
```

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

### GET /api/v1/voices

Source: https://viewmax.studio/docs/api/audio-generation

Retrieves a list of available text-to-speech voices and their associated credit costs.

```APIDOC
## GET /api/v1/voices

### Description
Returns the available text-to-speech voices and the per-generation credit cost.

### Method
GET

### Endpoint
/api/v1/voices
```

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

### CLI Command Reference

Source: https://viewmax.studio/docs/cli

Standard command syntax for interacting with the ViewMax API.

```bash
viewmax models [--json]
viewmax credits [--json]
viewmax generate -m <model> -p <prompt> [options]
viewmax task <task_id> [--wait] [--output file] [--json]
```

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

### Generate video with CLI

Source: https://viewmax.studio/docs/api/models/sora-2

Use the ViewMax CLI to trigger a video generation task with specific parameters.

```bash
viewmax generate -m sora-2 -p "A paper kite crossing a bright summer sky" \
  --duration 8s --resolution 720p --aspect-ratio 16:9 --audio --wait
```

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

### Create a video generation task

Source: https://viewmax.studio/docs

Initiates a new video generation task using the ViewMax REST API. Requires a valid API key and a supported model configuration.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "mode": "text-to-video",
    "prompt": "A paper kite crossing a bright summer sky",
    "options": {
      "duration": "8s",
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'
```

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

### Configure API Key

Source: https://viewmax.studio/docs/cli

Methods for setting the API key via configuration file or environment variable.

```bash
viewmax config set-key sk-your-api-key
```

```bash
export VIEWMAX_API_KEY=sk-your-api-key
```

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

### Generate video with CLI

Source: https://viewmax.studio/docs/api/models/kling-2-6

Command line interface usage for generating video with the kling-2-6 model.

```bash
viewmax generate -m kling-2-6 -p "A slow dolly through a neon-lit night market" \
  --duration 5s --audio --wait
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api/authentication

Create a new video resource.

```APIDOC
## POST /api/v1/videos

### Description
Creates a new video.

### Method
POST

### Endpoint
/api/v1/videos
```

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

### POST https://viewmax.studio/api/v1/videos

Source: https://viewmax.studio/docs/api/models/kling-2-6

Generates a video using the Kling 2.6 model by providing a prompt and configuration options.

```APIDOC
## POST https://viewmax.studio/api/v1/videos

### Description
Creates a new video generation task using the specified Kling model and parameters.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model identifier (e.g., "kling-2-6")
- **mode** (string) - Required - The generation mode (e.g., "text-to-video")
- **prompt** (string) - Required - The text prompt for generation
- **options** (object) - Optional - Configuration options including duration and audio settings

### Request Example
{
  "model": "kling-2-6",
  "mode": "text-to-video",
  "prompt": "A slow dolly through a neon-lit night market",
  "options": { "duration": "5s", "audio": true }
}
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api

Creates a credit-consuming video generation task.

```APIDOC
## POST /api/v1/videos

### Description
Creates a new video generation task. This operation is asynchronous.

### Method
POST

### Endpoint
/api/v1/videos
```

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

### Create an image task request headers

Source: https://viewmax.studio/docs/api/image-generation

The required headers for initiating an image generation task.

```http
POST https://viewmax.studio/api/v1/images
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api/models/grok-imagine

Generates a video from a text prompt or an image prompt using the specified Grok model.

```APIDOC
## POST /api/v1/videos

### Description
Creates a video generation task using Grok Imagine models. Supports both text-to-video and image-to-video modes.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model identifier (e.g., "grok-imagine", "grok-imagine-1-5")
- **mode** (string) - Required - The generation mode ("text-to-video" or "image-to-video")
- **prompt** (string) - Required - The text prompt for the video generation
- **image_urls** (array) - Optional - List of image URLs for image-to-video guidance (1-7 URLs)
- **options** (object) - Required - Configuration for the generation
  - **duration** (string) - Required - Video duration (e.g., "6s", "10s", "15s", "20s", "30s")
  - **resolution** (string) - Required - Video resolution (e.g., "480p", "720p")
  - **aspect_ratio** (string) - Required - Aspect ratio (e.g., "2:3", "3:2", "1:1", "9:16", "16:9")

### Request Example
{
  "model": "grok-imagine-1-5",
  "mode": "text-to-video",
  "prompt": "The camera slowly pushes toward the subject",
  "options": {
    "duration": "10s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
```

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

### POST /api/v1/music

Source: https://viewmax.studio/docs/api

Creates a music generation task.

```APIDOC
## POST /api/v1/music

### Description
Creates a new music generation task. This operation is synchronous.

### Method
POST

### Endpoint
/api/v1/music
```

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

### POST https://viewmax.studio/api/v1/videos

Source: https://viewmax.studio/docs/api/models/other-models

Generates a video using specified models like p-video, runway, or gemini-omni. The request requires authentication and specific model options.

```APIDOC
## POST https://viewmax.studio/api/v1/videos

### Description
Creates a new video generation task using the specified model and configuration options.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model identifier (e.g., "p-video", "runway", "gemini-omni-cheap", "gemini-omni-video").
- **mode** (string) - Required - The generation mode (e.g., "text-to-video", "image-to-video", "video-to-video").
- **prompt** (string) - Optional - The text prompt for generation.
- **image_urls** (array) - Optional - List of image URLs for image-to-video mode.
- **video_urls** (array) - Optional - List of video URLs for video-to-video mode.
- **options** (object) - Required - Configuration object containing duration, resolution, and aspect_ratio.

### Request Example
{
  "model": "p-video",
  "mode": "text-to-video",
  "prompt": "A red origami crane folding itself",
  "options": {
    "duration": "5s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs

Creates a new video generation task using a specified model and prompt.

```APIDOC
## POST /api/v1/videos

### Description
Creates a new video generation task.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model identifier (e.g., "sora-2")
- **mode** (string) - Required - The generation mode (e.g., "text-to-video")
- **prompt** (string) - Required - The text prompt for generation
- **options** (object) - Optional - Configuration options including duration, resolution, and aspect_ratio

### Request Example
{
  "model": "sora-2",
  "mode": "text-to-video",
  "prompt": "A paper kite crossing a bright summer sky",
  "options": {
    "duration": "8s",
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api/models/seedance

Initiates a video generation task using a specified Seedance or Seedence model.

```APIDOC
## POST /api/v1/videos

### Description
Creates a new video generation task. Users must specify the model ID and the desired generation mode along with configuration options.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model ID (e.g., "seedance-2-mini")
- **mode** (string) - Required - The generation mode (e.g., "text-to-video")
- **prompt** (string) - Required - The text prompt for generation
- **options** (object) - Optional - Configuration parameters including duration, resolution, aspect_ratio, and audio settings

### Request Example
{
  "model": "seedance-2-mini",
  "mode": "text-to-video",
  "prompt": "Ink clouds blooming in clear water",
  "options": {
    "duration": "4s",
    "resolution": "480p",
    "aspect_ratio": "1:1",
    "audio": true
  }
}
```

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

### viewmax generate

Source: https://viewmax.studio/docs/cli

Generates a video based on a model and prompt.

```APIDOC
## viewmax generate

### Description
Generates a video using the specified model and prompt.

### Parameters
- **-m, --model** (string) - Required - Model ID
- **-p, --prompt** (string) - Required - Prompt
- **--mode** (string) - Optional - Video mode such as text-to-video
- **--image** (url) - Optional - Source image URL
- **--duration** (string) - Optional - Model-supported duration (e.g., 8s)
- **--resolution** (string) - Optional - Model-supported resolution (e.g., 720p)
- **--aspect-ratio** (string) - Optional - Model-supported aspect ratio (e.g., 16:9)
- **--audio** (flag) - Optional - Enables audio when supported
- **--wait** (flag) - Optional - Poll every 5 seconds for up to 10 minutes
- **--output** (file) - Optional - Download the first completed video URL to a file
- **--json** (flag) - Optional - Print bare JSON for automation
```

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

### POST /api/v1/music

Source: https://viewmax.studio/docs/api/music-generation

Generates an original music track from a text prompt and consumes credits.

```APIDOC
## POST /api/v1/music

### Description
Generates an original music track from a text prompt and consumes credits when accepted.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/music

### Request Body
- **prompt** (string) - Required - Non-empty description of the track
- **options** (object) - Optional - Generation controls
  - **duration_seconds** (number) - Target length, 3–300
  - **instrumental** (boolean) - true for no vocals
  - **style** (string) - Optional style/genre hint
  - **lyrics** (string) - Optional lyrics

### Request Example
{
  "prompt": "Warm lo-fi hip-hop with a mellow piano loop",
  "options": { "duration_seconds": 30, "instrumental": true }
}

### Response
#### Success Response (200)
- **code** (number) - Status code
- **message** (string) - Status message
- **data** (object) - Task details
  - **id** (string) - Task ID
  - **status** (string) - Task status
  - **costCredits** (number) - Credits consumed
  - **taskUrls** (array) - List of result URLs

#### Response Example
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "success",
    "costCredits": 10,
    "taskUrls": ["https://.../music.mp3"]
  }
}
```

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

### Generate video with cURL

Source: https://viewmax.studio/docs/api/models/other-models

Use the ViewMax API v1 endpoint to generate a video by specifying the model, mode, and generation options.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "p-video",
    "mode": "text-to-video",
    "prompt": "A red origami crane folding itself",
    "options": {
      "duration": "5s",
      "resolution": "720p",
      "aspect_ratio": "16:9"
    }
  }'
```

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

### Create a video task request header

Source: https://viewmax.studio/docs/api/video-generation

The base request structure for initiating a video generation task via the API.

```http
POST https://viewmax.studio/api/v1/videos
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api/models/sora-2

Generates a video using the specified Sora 2 model based on text or image input.

```APIDOC
## POST /api/v1/videos

### Description
Generates a cinematic video from text or image prompts using the Sora 2 or Sora 2 Pro models.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model to use (e.g., "sora-2", "sora-2-pro")
- **mode** (string) - Required - The generation mode ("text-to-video" or "image-to-video")
- **prompt** (string) - Required - The text prompt for the video
- **image_urls** (array) - Optional - Public image URLs for image-to-video generation
- **options** (object) - Required - Configuration for the generation:
  - **duration** (string) - Required - Duration (e.g., "4s", "8s", "12s")
  - **resolution** (string) - Required - Resolution (e.g., "720p", "1080p")
  - **aspect_ratio** (string) - Required - Aspect ratio (e.g., "16:9", "9:16")
  - **audio** (boolean) - Required - Enable or disable audio

### Request Example
{
  "model": "sora-2",
  "mode": "text-to-video",
  "prompt": "A paper kite crossing a bright summer sky",
  "options": {
    "duration": "8s",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": true
  }
}
```

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

### ViewMax MCP Tools

Source: https://viewmax.studio/docs/mcp

The ViewMax MCP server exposes various tools for media generation and task management. These tools are invoked via the MCP protocol.

```APIDOC
## MCP Tools Overview

### Shared Tools
- **get_task(task_id)**: Retrieves current status, media type, and output URLs for a task.
- **wait_for_task(task_id, timeout_seconds)**: Polls for a task result; default 45s, max 50s.
- **get_credits()**: Returns remaining credits for the authenticated account.

### Video Tools
- **list_video_models()**: Lists available video model IDs and capabilities.
- **get_video_model(model)**: Retrieves full capability and pricing data for a specific video model.
- **generate_video(model, prompt, ...)**: Creates a video generation task; returns task_id and cost.

### Image Tools
- **list_image_models()**: Lists available image models and their attributes.
- **get_image_model(model)**: Retrieves capability and pricing data for an image model.
- **generate_image(model, prompt, ...)**: Creates an image generation task.

### Music Tools
- **list_music_models()**: Lists available music models and costs.
- **generate_music(prompt, ...)**: Renders music synchronously and returns output URLs.

### Audio Tools
- **list_voices()**: Lists available text-to-speech voices and costs.
- **generate_speech(text, voice_id, ...)**: Renders speech synchronously.
- **generate_sound_effect(prompt, ...)**: Renders sound effects synchronously.
```

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

### Generate video with cURL

Source: https://viewmax.studio/docs/api/models/sora-2

Submit a text-to-video generation request to the ViewMax API using a POST request.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "mode": "text-to-video",
    "prompt": "A paper kite crossing a bright summer sky",
    "options": {
      "duration": "8s",
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "audio": true
    }
  }'
```

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

### List available voices

Source: https://viewmax.studio/docs/api/audio-generation

Retrieves a list of available text-to-speech voices and their associated credit costs.

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/voices
```

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

### POST /api/v1/images

Source: https://viewmax.studio/docs/api/image-generation

Creates an image-generation task and consumes credits when accepted.

```APIDOC
## POST /api/v1/images

### Description
Creates an image-generation task and consumes credits when accepted.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/images

### Parameters
#### Request Body
- **model** (string) - Required - A current model ID from GET /api/v1/models?type=image
- **prompt** (string) - Required - Non-empty image instruction
- **scene** (string) - Optional - text-to-image or image-to-image; must be supported by the model
- **image_urls** (string[]) - Optional - Public HTTP(S) image URLs; required for image-to-image
- **options** (object) - Optional - Model-specific generation controls (aspect_ratio, quality)

### Request Example
{
  "model": "nano-banana-2",
  "scene": "text-to-image",
  "prompt": "A paper kite crossing a bright summer sky",
  "options": { "aspect_ratio": "16:9", "quality": "2K" }
}

### Response
#### Success Response (200)
- **code** (integer) - Status code
- **message** (string) - Status message
- **data** (object) - Task details including id, status, and costCredits

#### Response Example
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "processing",
    "costCredits": 8
  }
}
```

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

### POST /api/v1/videos

Source: https://viewmax.studio/docs/api/models/veo-3-1

Generates a video using the specified Veo 3.1 model, mode, and generation options.

```APIDOC
## POST /api/v1/videos

### Description
Generates a video based on the provided prompt or image inputs using the Veo 3.1 model family.

### Method
POST

### Endpoint
https://viewmax.studio/api/v1/videos

### Request Body
- **model** (string) - Required - The model identifier (e.g., "veo-3-1", "veo-3-1-fast", "veo-3-1-lite").
- **mode** (string) - Required - The generation mode: "text-to-video", "image-to-video", "frames-to-video", or "reference-to-video".
- **prompt** (string) - Optional - The text prompt for generation.
- **image_urls** (array) - Optional - List of image URLs for frames-to-video (min 2) or reference-to-video (1-3).
- **options** (object) - Optional - Generation settings including "resolution" (720p, 1080p, 4k) and "aspect_ratio" (16:9, 9:16, Auto).

### Request Example
{
  "model": "veo-3-1-fast",
  "mode": "text-to-video",
  "prompt": "A glass terrarium on a sunlit desk",
  "options": { "resolution": "720p", "aspect_ratio": "16:9" }
}
```

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

### Generate video via cURL

Source: https://viewmax.studio/docs/api/models/veo-3-1

Use this request to trigger a video generation task using the Veo 3.1 Fast model via the ViewMax API.

```bash
curl -X POST https://viewmax.studio/api/v1/videos \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-1-fast",
    "mode": "text-to-video",
    "prompt": "A glass terrarium on a sunlit desk",
    "options": { "resolution": "720p", "aspect_ratio": "16:9" }
  }'
```

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

### POST /api/v1/images

Source: https://viewmax.studio/docs/api

Creates an image generation task.

```APIDOC
## POST /api/v1/images

### Description
Creates a new image generation task. This operation is asynchronous.

### Method
POST

### Endpoint
/api/v1/images
```

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

### POST /api/v1/speech

Source: https://viewmax.studio/docs/api

Converts text to speech.

```APIDOC
## POST /api/v1/speech

### Description
Converts provided text to speech. This operation is synchronous.

### Method
POST

### Endpoint
/api/v1/speech
```

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

### viewmax credits

Source: https://viewmax.studio/docs/cli

Prints the authenticated account's remaining credits.

```APIDOC
## viewmax credits

### Description
Prints the authenticated account's remaining credits.

### Parameters
- **--json** (flag) - Optional - Print bare JSON for automation.
```

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

### Successful response structure

Source: https://viewmax.studio/docs/api/image-generation

The JSON response returned upon successfully creating an image task.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "processing",
    "costCredits": 8
  }
}
```

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

### viewmax models

Source: https://viewmax.studio/docs/cli

Lists the public v1 model catalog.

```APIDOC
## viewmax models

### Description
Lists the public v1 model catalog.

### Parameters
- **--json** (flag) - Optional - Print bare JSON for automation.
```

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

### Successful response structure

Source: https://viewmax.studio/docs/api/video-generation

The JSON response returned upon successfully creating a video generation task.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "pending",
    "costCredits": 20
  }
}
```

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

### Retrieve task status via HTTP

Source: https://viewmax.studio/docs/api/tasks

Use this endpoint to fetch the current status and output URLs for a specific video task.

```http
GET https://viewmax.studio/api/v1/tasks/{taskId}
Authorization: Bearer sk-your-api-key
```

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/tasks/task_123
```

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

### POST /api/v1/sound-effects

Source: https://viewmax.studio/docs/api/audio-generation

Generates a sound effect based on a descriptive text prompt.

```APIDOC
## POST /api/v1/sound-effects

### Description
Generates a sound effect from a text prompt.

### Method
POST

### Endpoint
/api/v1/sound-effects

### Parameters
#### Request Body
- **prompt** (string) - Required - Non-empty description of the sound
- **options** (object) - Optional - duration_seconds (0.5–22), prompt_influence (0–1)
```

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

### POST /api/v1/sound-effects

Source: https://viewmax.studio/docs/api

Generates a sound effect.

```APIDOC
## POST /api/v1/sound-effects

### Description
Generates a sound effect. This operation is synchronous.

### Method
POST

### Endpoint
/api/v1/sound-effects
```

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

### API Base URL

Source: https://viewmax.studio/docs/api

The root URL for all ViewMax v1 API requests.

```text
https://viewmax.studio
```

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

### viewmax task

Source: https://viewmax.studio/docs/cli

Reads a task by ID.

```APIDOC
## viewmax task <task_id>

### Description
Reads a task by ID.

### Parameters
- **task_id** (string) - Required - The ID of the task to retrieve
- **--wait** (flag) - Optional - Poll the task status
- **--output** (file) - Optional - Download the first completed video URL to a file
- **--json** (flag) - Optional - Print bare JSON for automation
```

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

### ViewMax MCP Server Endpoint

Source: https://viewmax.studio/docs/mcp

The base URL for the ViewMax remote Streamable HTTP MCP server.

```text
https://viewmax.studio/api/mcp
```

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

### Generate sound effects

Source: https://viewmax.studio/docs/api/audio-generation

Generates a sound effect based on a text prompt with optional duration and influence settings.

```bash
curl -X POST https://viewmax.studio/api/v1/sound-effects \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A distant rolling thunder clap", "options": { "duration_seconds": 5 } }'
```

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

### Music Generation API Request Headers

Source: https://viewmax.studio/docs/api/music-generation

Required headers for authenticating and specifying content type for music generation requests.

```HTTP
POST https://viewmax.studio/api/v1/music
Authorization: Bearer sk-your-api-key
Content-Type: application/json
```

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

### Generate speech from text

Source: https://viewmax.studio/docs/api/audio-generation

Converts text to speech using a specified voice ID and optional parameters like speed and stability.

```bash
curl -X POST https://viewmax.studio/api/v1/speech \
  -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to ViewMax.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "options": { "speed": 1.0 }
  }'
```

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

### Authentication Header

Source: https://viewmax.studio/docs/api/authentication

All authenticated v1 requests require an Authorization header with a Bearer token.

```APIDOC
## Authentication

### Description
Send the API key on every authenticated v1 request using the Authorization header.

### Header
`Authorization: Bearer sk-your-api-key`

### Error Handling
Missing or invalid credentials return HTTP 401 with `code: -1001`.
```

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

### POST /api/v1/speech

Source: https://viewmax.studio/docs/api/audio-generation

Converts provided text into speech using a specified voice ID.

```APIDOC
## POST /api/v1/speech

### Description
Converts text to speech with a selected voice.

### Method
POST

### Endpoint
/api/v1/speech

### Parameters
#### Request Body
- **text** (string) - Required - Non-empty text to speak
- **voice_id** (string) - Required - A voice id from GET /api/v1/voices
- **options** (object) - Optional - model_id, speed (0.25–4), stability (0–1), similarity_boost (0–1)
```

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

### Successful Music Generation Response

Source: https://viewmax.studio/docs/api/music-generation

The JSON structure returned upon a successful music generation request, including task ID and result URLs.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "task_123",
    "status": "success",
    "costCredits": 10,
    "taskUrls": ["https://.../music.mp3"]
  }
}
```

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

### Send API Key via Authorization Header

Source: https://viewmax.studio/docs/api/authentication

Include the API key in the Authorization header for all authenticated v1 requests.

```HTTP
Authorization: Bearer sk-your-api-key
```

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

### Standard API Response Envelope

Source: https://viewmax.studio/docs/api

All v1 API responses follow this JSON structure. Use the HTTP status for transport handling and the 'code' field for business logic results.

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

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

### Poll task status

Source: https://viewmax.studio/docs

Retrieves the current status of a video generation task using its unique ID. Poll this endpoint until the task reaches a terminal state.

```bash
curl -H "Authorization: Bearer $VIEWMAX_API_KEY" \
  https://viewmax.studio/api/v1/tasks/TASK_ID
```
Tokens:
Raw