MuapiClient

Overview

The MuapiClient class provides a JavaScript interface for generating images and videos through the Muapi API. It handles authentication, request submission, and result polling automatically.

Installation

import { MuapiClient } from './lib/muapi.js';

Constructor

const client = new MuapiClient();

The constructor automatically sets the base URL based on the environment:

Development: Uses empty string (proxied requests)
Production: Uses https://api.muapi.ai

Authentication

The client retrieves the API key from localStorage:

getKey()

The API key must be stored in localStorage under the key muapi_key. If missing, an error is thrown.

Setting the API Key

localStorage.setItem('muapi_key', 'your-api-key-here');

Submit and Poll Pattern

All generation methods follow a two-step pattern:

Submit: POST request to the model endpoint
Poll: Retrieve results from /api/v1/predictions/{request_id}/result

Polling Configuration

pollForResult(requestId, key, maxAttempts = 60, interval = 2000)

requestId

string

required

The request ID returned from the submit response

key

string

required

The API key for authentication

maxAttempts

number

default:"60"

Maximum polling attempts (default ~2 minutes)

interval

number

default:"2000"

Polling interval in milliseconds

Image Generation

generateImage()

Generate images using Text-to-Image or Image-to-Image models.

const result = await client.generateImage({
  model: 'flux-dev',
  prompt: 'A serene mountain landscape at sunset',
  aspect_ratio: '16:9',
  seed: 42,
  image_url: null // Optional: for Image-to-Image
});

model

string

required

Model ID from the model catalog (e.g., flux-dev, midjourney-v7-text-to-image)

prompt

string

required

Text description of the desired image

aspect_ratio

string

Aspect ratio (e.g., 1:1, 16:9, 9:16)

resolution

string

Resolution option (e.g., 1k, 2k, 4k) - varies by model

quality

string

Quality setting (e.g., basic, high) - varies by model

seed

number

Random seed for reproducible results (-1 for random)

image_url

string

For Image-to-Image: URL of the reference image

strength

number

default:"0.6"

For Image-to-Image: Transformation strength (0-1)

url

string

The generated image URL

outputs

array

Array of output URLs (first item is the primary result)

status

string

Generation status (completed, succeeded, success)

Example: Text-to-Image

const result = await client.generateImage({
  model: 'flux-dev',
  prompt: 'Extreme close-up of a tiger eye with FLUX painted over it',
  aspect_ratio: '1:1'
});

console.log(result.url); // https://...

Example: Image-to-Image

const result = await client.generateImage({
  model: 'flux-dev',
  prompt: 'Transform into a watercolor painting',
  image_url: 'https://example.com/uploaded-image.jpg',
  strength: 0.7,
  aspect_ratio: '16:9'
});

Video Generation

generateVideo()

Generate videos using Text-to-Video models.

const result = await client.generateVideo({
  model: 'kling-v2.6-pro-t2v',
  prompt: 'A cat playing with a ball of yarn',
  aspect_ratio: '16:9',
  duration: 5,
  resolution: '720p'
});

model

string

required

Video model ID (e.g., kling-v2.6-pro-t2v, runway-text-to-video)

prompt

string

required

Text description of the desired video

aspect_ratio

string

Video aspect ratio (e.g., 16:9, 9:16, 1:1)

duration

number

Video duration in seconds (varies by model)

resolution

string

Video resolution (e.g., 480p, 720p, 1080p)

quality

string

Quality setting (e.g., basic, high, medium)

Video generation uses longer polling: 120 attempts at 2-second intervals (~4 minutes)

Image-to-Image Generation

generateI2I()

Generate images using dedicated Image-to-Image models with custom image field handling.

const result = await client.generateI2I({
  model: 'flux-kontext-dev-i2i',
  image_url: 'https://example.com/reference.jpg',
  prompt: 'Add magical glowing effects',
  aspect_ratio: '1:1'
});

model

string

required

I2I model ID from the catalog

image_url

string

required

URL of the uploaded reference image

images_list

array

Array of image URLs for models that support multiple images

prompt

string

Optional text prompt (depends on model support)

aspect_ratio

string

Output aspect ratio

resolution

string

Output resolution

quality

string

Output quality

The imageField property from the model definition determines which payload key receives the image URL(s). Common fields: image_url, images_list, model_image_url

Multi-Image Support

const result = await client.generateI2I({
  model: 'flux-kontext-dev-i2i',
  images_list: [
    'https://example.com/ref1.jpg',
    'https://example.com/ref2.jpg'
  ],
  prompt: 'Combine these styles'
});

Image-to-Video Generation

generateI2V()

Generate videos from a starting frame image.

const result = await client.generateI2V({
  model: 'runway-image-to-video',
  image_url: 'https://example.com/start-frame.jpg',
  prompt: 'Camera slowly zooms in',
  duration: 5,
  aspect_ratio: '16:9'
});

model

string

required

I2V model ID from the catalog

image_url

string

required

URL of the starting frame image

prompt

string

Optional motion description

aspect_ratio

string

Video aspect ratio

duration

number

Video duration in seconds

resolution

string

Video resolution

quality

string

Video quality

File Upload

uploadFile()

Upload an image file to Muapi’s hosting service.

const fileUrl = await client.uploadFile(file);

file

File

required

The image file to upload (browser File object)

fileUrl

string

The hosted URL of the uploaded file

Upload Workflow

User selects file from input
Upload file to get hosted URL
Use URL in generation requests

// Example: Complete I2I workflow
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];

// Upload the file
const fileUrl = await client.uploadFile(file);

// Use in generation
const result = await client.generateI2I({
  model: 'flux-kontext-dev-i2i',
  image_url: fileUrl,
  prompt: 'Transform into a painting'
});

The upload endpoint returns JSON with a url, file_url, or data.url field containing the hosted URL.

Error Handling

Common Errors

try {
  const result = await client.generateImage(params);
} catch (error) {
  if (error.message.includes('API Key missing')) {
    // No API key in localStorage
  } else if (error.message.includes('API Request Failed')) {
    // HTTP error from API
  } else if (error.message.includes('Generation failed')) {
    // Model generation failed
  } else if (error.message.includes('timed out')) {
    // Polling timeout exceeded
  }
}

API errors include the status code and response text (truncated to 100 characters).

Request Headers

All requests include:

headers: {
  'Content-Type': 'application/json',
  'x-api-key': key
}

File uploads use:

headers: {
  'x-api-key': key
}
// Content-Type is automatically set by FormData

Utility Methods

getDimensionsFromAR()

Convert aspect ratio string to width/height dimensions (1024px base).

const [width, height] = client.getDimensionsFromAR('16:9');
// Returns: [1280, 720]

dimensions

array

[width, height] in pixels

Supported Ratios:

1:1 → [1024, 1024]
16:9 → [1280, 720]
9:16 → [720, 1280]
4:3 → [1152, 864]
3:2 → [1216, 832]
21:9 → [1536, 640]

Complete Example

import { muapi } from './lib/muapi.js';

// Set API key
localStorage.setItem('muapi_key', 'your-key');

// Upload reference image
const file = document.querySelector('input').files[0];
const imageUrl = await muapi.uploadFile(file);

// Generate image-to-image
const i2iResult = await muapi.generateI2I({
  model: 'flux-kontext-dev-i2i',
  image_url: imageUrl,
  prompt: 'Transform into cyberpunk style',
  aspect_ratio: '16:9'
});

// Generate video from result
const videoResult = await muapi.generateI2V({
  model: 'runway-image-to-video',
  image_url: i2iResult.url,
  prompt: 'Camera pans slowly to the right',
  duration: 5
});

console.log('Video URL:', videoResult.url);

Singleton Instance

A pre-configured client instance is exported:

import { muapi } from './lib/muapi.js';

await muapi.generateImage({ /* ... */ });

API Client

Models

Overview

Installation

Constructor

Authentication

Setting the API Key

Submit and Poll Pattern

Polling Configuration

Image Generation

generateImage()

Example: Text-to-Image

Example: Image-to-Image

Video Generation

generateVideo()

Image-to-Image Generation

generateI2I()

Multi-Image Support

Image-to-Video Generation

generateI2V()

File Upload

uploadFile()

Upload Workflow

Error Handling

Common Errors

Request Headers

Utility Methods

getDimensionsFromAR()

Complete Example

Singleton Instance

Build docs developers (and LLMs) love

API Client

Models

​Overview

​Installation

​Constructor

​Authentication

​Setting the API Key

​Submit and Poll Pattern

​Polling Configuration

​Image Generation

​generateImage()

​Example: Text-to-Image

​Example: Image-to-Image

​Video Generation

​generateVideo()

​Image-to-Image Generation

​generateI2I()

​Multi-Image Support

​Image-to-Video Generation

​generateI2V()

​File Upload

​uploadFile()

​Upload Workflow

​Error Handling

​Common Errors

​Request Headers

​Utility Methods

​getDimensionsFromAR()

​Complete Example

​Singleton Instance

Build docs developers (and LLMs) love

Overview

Installation

Constructor

Authentication

Setting the API Key

Submit and Poll Pattern

Polling Configuration

Image Generation

generateImage()

Example: Text-to-Image

Example: Image-to-Image

Video Generation

generateVideo()

Image-to-Image Generation

generateI2I()

Multi-Image Support

Image-to-Video Generation

generateI2V()

File Upload

uploadFile()

Upload Workflow

Error Handling

Common Errors

Request Headers

Utility Methods

getDimensionsFromAR()

Complete Example

Singleton Instance