Muse APIdocs Models Pricing
English
Sign in Get an API key
API reference

Muse API

Muse API provides chat, image generation and video generation through OpenAI-compatible endpoints. If you already use an OpenAI SDK, just change base_url and your API key — requests and responses keep the same format.

Base URLhttps://muse.isemi.io/v1

Quickstart #

  1. Buy credit with PayPal or a card and get an API key (m2a-…) instantly.
  2. Install the OpenAI SDK: pip install openai or npm install openai.
  3. Point the client at Muse API and send your first request:
from openai import OpenAI

client = OpenAI(base_url="https://muse.isemi.io/v1", api_key="m2a-your-key")

resp = client.chat.completions.create(
    model="muse-chat",
    messages=[{"role": "user", "content": "Write a one-line good-morning message"}],
)
print(resp.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://muse.isemi.io/v1", apiKey: "m2a-your-key" });

const resp = await client.chat.completions.create({
  model: "muse-chat",
  messages: [{ role: "user", content: "Write a one-line good-morning message" }],
});
console.log(resp.choices[0].message.content);
curl https://muse.isemi.io/v1/chat/completions \
  -H "Authorization: Bearer $MUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "muse-chat", "messages": [{"role": "user", "content": "Write a one-line good-morning message"}]}'

Authentication #

Every /v1/* endpoint (except result files) requires an API key, sent in either header:

HTTP headers
Authorization: Bearer m2a-your-key
# or
X-Api-Key: m2a-your-key

A missing, invalid or revoked key returns 401 with "code": "invalid_api_key".

Keep your key on the server. Never embed it in frontend code, mobile apps or public repositories — anyone holding the key can spend your balance. If a key leaks, email company@isemi.io to revoke it and get a new one.

Models #

Choose a model with the model parameter. Each endpoint accepts only models of its own kind; leave model empty to use the endpoint's default.

ModelKindEndpointCapabilities
muse-chatChat/v1/chat/completionsMulti-turn chat, system prompts, streaming, image input
muse-imageImage/v1/images/generations
/v1/images/edits
Text-to-image, reference images (up to 4), transparent background
muse-videoVideo/v1/videosText-to-video, image-to-video (first frame)

Compatible model names

So that existing tools work without reconfiguration, the names below are accepted and routed to the matching Muse model. They are aliases only — the request is still served by the Muse model.

Name you sendServed by
gpt-4o · gpt-4o-mini · gpt-4.1 · gpt-5 · claude-sonnet-4 · deepseek-chatmuse-chat
dall-e-3 · gpt-image-1muse-image
soramuse-video

Model names not on the list fall back to the endpoint's default model. Sending a model of the wrong kind (for example muse-video to chat) returns 400.

Pricing & billing #

Muse API is prepaid: you top up USD credit to your API key and each successful request is deducted from that balance.

ModelPriceCharged on
muse-image$0.015 per imageEach generated image; n images cost n × the price. Transparent background costs nothing extra.
muse-video$0.006 per secondThe duration you request (duration / seconds), or 10 seconds if you don't set one — a 10-second video costs $0.06.
muse-chat$1 per 1M input tokens
$3 per 1M output tokens
Prompt tokens (the messages you send) and completion tokens (the reply).

How charges work

  • Images and video: the price is reserved when the request is accepted. If generation fails, is cancelled or is interrupted, the full amount is refunded automatically.
  • Chat: charged when the reply finishes, for the tokens actually used. A streamed reply that you stop early is charged for the output produced so far.
  • Failed requests are free. Errors such as 400, 401, 402 or a failed generation never cost anything.
  • Every response shows its cost: usage.cost_usd for chat, cost_usd for images and on every task object.

Tokens are counted by the gateway: about 4 characters per token for Latin-script text and 1 token per Chinese, Japanese or Korean character. The same numbers are returned in usage, so what you see is what you pay.

To top up, open /billing and pay with PayPal or a debit or credit card — the credit is added instantly, to a new key or to one you already have. For invoices or other payment methods, email company@isemi.io. Check your remaining credit at any time with GET /v1/balance. When the balance is too low for a request, the API answers 402 insufficient_balance and nothing is charged.

Chat completions #

POST/v1/chat/completions

Compatible with OpenAI's client.chat.completions.create(), both streaming and non-streaming.

Parameters

modelstring

muse-chat or a compatible name.

Default: muse-chat

messagesrequiredarray

The conversation history. role is system (or developer), user or assistant. content is a string, or an array of {"type": "text"} and {"type": "image_url"} parts (see image input).

streamboolean

Return the reply in chunks over Server-Sent Events.

Default: false

stream_optionsobject

{"include_usage": true} adds a final chunk with usage (including cost_usd).

userstring

A stable ID for one conversation (for example your chat session ID). Sending the same value on follow-up turns makes replies faster. Always send the full messages history anyway.

temperature, top_p, max_tokens, tools, tool_choice

Accepted for compatibility but currently have no effect.

Response

200 OK
{
  "id": "chatcmpl-8f2c1e0b9a7d4c3e2f1a0b9c",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "muse-chat",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Good morning — make today a great one!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 10, "total_tokens": 19, "cost_usd": 0.000039 }
}

usage holds the billed token counts and cost_usd, the amount deducted for this request.

Streaming

With "stream": true the response is text/event-stream: each data: line carries a chat.completion.chunk, ending with data: [DONE].

stream = client.chat.completions.create(
    model="muse-chat",
    messages=[{"role": "user", "content": "Tell a short story about autumn"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
const stream = await client.chat.completions.create({
  model: "muse-chat",
  messages: [{ role: "user", content: "Tell a short story about autumn" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Autumn"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" leaves"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

If an error happens after the stream has started, the server sends a data: {"error": {…}} event followed by data: [DONE]. Errors before the first content arrive as a normal HTTP status.

Image input

Add an image_url part to content. The URL can be http(s)://… or a data URL data:image/png;base64,….

Python
resp = client.chat.completions.create(
    model="muse-chat",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this photo in two sentences"},
            {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}},
        ],
    }],
)

Image generation #

POST/v1/images/generations

Compatible with client.images.generate(). Generates images from a prompt, optionally with reference images.

Parameters

promptrequiredstring

Describes the image to create. With reference images, say how to use them (for example “keep the same character, move the scene to a beach”).

modelstring

Default: muse-image

ninteger

Number of images to create, 1 to 4. Each image is billed.

Default: 1

sizestring

Aspect ratio, for example 1:1, 16:9, 9:16, 4:3.

response_formatstring

url returns a download link; b64_json returns the image base64-encoded inside the response.

Default: url

backgroundstring

transparent cuts out the subject and returns a transparent PNG (about 30 seconds extra per image, no extra charge). auto / opaque keep the image as generated.

imagestring | string[]

One or up to 4 reference images: data URL, http(s) URL or a base64 string.

asyncboolean

Return a task immediately and poll it, instead of waiting for the image. Recommended — see the note below.

Default: false

Use "async": true. An image usually takes 1–2 minutes and can take longer at peak times. A synchronous request keeps the connection open the whole time and may be cut by a proxy or HTTP client (commonly HTTP 524 after about 100 seconds). Async mode returns at once and has no such limit.

Example

img = client.images.generate(
    model="muse-image",
    prompt="A red fox sitting in an autumn forest, morning light, photorealistic",
    size="16:9",
)
print(img.data[0].url)
curl https://muse.isemi.io/v1/images/generations \
  -H "Authorization: Bearer $MUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A red fox sitting in an autumn forest, morning light", "size": "16:9"}'
200 OK
{
  "created": 1767225600,
  "data": [
    {
      "url": "https://muse.isemi.io/v1/media/img_3f9a1c2b7d4e5f60.png",
      "revised_prompt": "A red fox sitting in an autumn forest, morning light"
    }
  ],
  "cost_usd": 0.015
}

Reference images

Send images in the image field to keep a character, product or style. For example, putting a product on a model:

cURL
curl https://muse.isemi.io/v1/images/generations \
  -H "Authorization: Bearer $MUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A model wearing exactly this hoodie, studio photo",
    "image": ["https://example.com/hoodie.jpg"],
    "async": true
  }'

Async mode

With "async": true the response is a task. Poll GET /v1/images/generations/{id} until status is succeeded; its result then has the same shape as the synchronous response above. In this mode images are always returned as url.

GET/v1/images/generations/{id}
Python
import time, requests

BASE = "https://muse.isemi.io/v1"
HEADERS = {"Authorization": "Bearer m2a-your-key"}

task = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "prompt": "A red fox sitting in an autumn forest",
    "async": True,
}).json()

while task["status"] in ("queued", "running"):
    time.sleep(5)
    task = requests.get(f"{BASE}/images/generations/{task['id']}", headers=HEADERS).json()

if task["status"] == "succeeded":
    print(task["result"]["data"][0]["url"])
else:
    print("Error:", task["error"])

Reference images (multipart) #

POST/v1/images/edits

Compatible with client.images.edit(): upload image files as multipart/form-data instead of sending URLs. The images are used as references to create a new image.

image / image[]requiredfile

1 to 4 image files.

promptrequiredstring

Describes the image to create from the references.

n, size, response_format, background, async
maskfile

Not supported — a request with mask returns 400.

img = client.images.edit(
    model="muse-image",
    image=[open("fox.png", "rb")],
    prompt="The same fox, now wearing a red scarf",
)
print(img.data[0].url)
curl https://muse.isemi.io/v1/images/edits \
  -H "Authorization: Bearer $MUSE_API_KEY" \
  -F "image[]=@fox.png" \
  -F "prompt=The same fox, now wearing a red scarf" \
  -F "async=true"

Video generation #

POST/v1/videos
GET/v1/videos/{id}

Video generation always runs as a task: POST returns a task right away, then poll GET /v1/videos/{id} until it finishes.

Parameters

promptrequiredstring

Describes the video content.

modelstring

Default: muse-video

sizestring

Aspect ratio, for example 16:9 or 9:16.

duration / secondsinteger

Desired length in seconds (1–60). This is what you are billed on ($0.006 per second); the actual clip length may differ slightly.

Default: 10

image / input_referencestring

An image to use as the first frame (image-to-video): data URL or http(s) URL.

# 1. Create the task
curl https://muse.isemi.io/v1/videos \
  -H "Authorization: Bearer $MUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Maple leaves falling in a light breeze", "duration": 10, "size": "16:9"}'

# 2. Poll until status = succeeded
curl https://muse.isemi.io/v1/videos/task_9b1e4f2a7c3d8e60 \
  -H "Authorization: Bearer $MUSE_API_KEY"
import time, requests

BASE = "https://muse.isemi.io/v1"
HEADERS = {"Authorization": "Bearer m2a-your-key"}

task = requests.post(f"{BASE}/videos", headers=HEADERS, json={
    "prompt": "Maple leaves falling in a light breeze",
    "duration": 10,
    "size": "16:9",
}).json()

while task["status"] in ("queued", "running"):
    time.sleep(10)
    task = requests.get(f"{BASE}/videos/{task['id']}", headers=HEADERS).json()
    print(task["status"], task["progress"])

print(task["result"]["url"] if task["status"] == "succeeded" else task["error"])
GET /v1/videos/{id}
{
  "id": "task_9b1e4f2a7c3d8e60",
  "object": "video",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1767225600,
  "model": "muse-video",
  "result": {
    "url": "https://muse.isemi.io/v1/media/vid_5c2e8a1f0b3d4e79.mp4",
    "mime": "video/mp4",
    "width": 1280,
    "height": 720
  },
  "error": null,
  "cost_usd": 0.06
}

Async tasks #

Video, and images in async mode, return a task. All tasks share this structure:

idstring

task_…, used for polling.

objectstring

image.task or video.

statusstring
queued→running→succeeded|failed|cancelled
progressinteger

Estimated progress, 0–100.

resultobject | null

Present when succeeded. Images: {"created", "data": [{"url"}]}. Video: {"url", "mime", "width", "height"} (width / height may be null).

errorobject | null

Present when failed: {"message", "code"}.

cost_usdnumber

The amount reserved for this task. It is refunded if the task ends failed or cancelled.

Polling every 5 seconds for images and every 10 seconds for video is plenty. Polling is free. Tasks are kept for a limited time, so save the result as soon as a task completes.

Result files #

GET/v1/media/{name}

Generated images and videos are returned as /v1/media/… URLs. This endpoint needs no API key, so the links can go straight into <img> / <video> tags; file names are random and cannot be guessed.

Links are not guaranteed to last. Download the file and store it on your side as soon as you receive it.

Balance #

GET/v1/balance

Returns the remaining credit of the key making the request. unlimited is true for keys that are not billed, in which case balance_usd is null.

curl https://muse.isemi.io/v1/balance -H "Authorization: Bearer $MUSE_API_KEY"
import requests

r = requests.get("https://muse.isemi.io/v1/balance",
                 headers={"Authorization": "Bearer m2a-your-key"})
print(r.json()["balance_usd"])
200 OK
{
  "object": "balance",
  "balance_usd": 12.34,
  "currency": "USD",
  "unlimited": false
}

List models #

GET/v1/models

Compatible with client.models.list(). Returns the models and compatible names; each entry also carries kind (chat / image / video), and compatible names carry alias_of.

200 OK
{
  "object": "list",
  "data": [
    { "id": "muse-chat", "object": "model", "created": 1767225600, "owned_by": "muse", "kind": "chat" },
    { "id": "muse-image", "object": "model", "created": 1767225600, "owned_by": "muse", "kind": "image" },
    { "id": "muse-video", "object": "model", "created": 1767225600, "owned_by": "muse", "kind": "video" },
    { "id": "gpt-4o", "object": "model", "created": 1767225600, "owned_by": "muse", "kind": "chat", "alias_of": "muse-chat" }
  ]
}

Errors & retries #

Errors return an HTTP status with a body in the same format as OpenAI, so the SDKs raise the matching exception (AuthenticationError, BadRequestError, …):

Error body
{
  "error": {
    "message": "insufficient balance: this request costs $0.015000, balance is $0.004000; top up to continue",
    "type": "insufficient_quota",
    "code": "insufficient_balance"
  }
}
StatusMeaningWhat to do
400Invalid parameters (missing prompt, more than 4 images, model of the wrong kind…)Fix the request according to message; do not retry it unchanged
401API key missing, invalid or revokedCheck your key
402Balance too low for this request (insufficient_balance); nothing was chargedTop up credit, then retry
404Task or file not foundCheck the ID; old tasks may have been cleaned up
429Temporarily out of capacityRetry after a few tens of seconds
501Feature not supported yetSee limits
502Generation failedRetry; if it keeps failing with the same prompt, rephrase the prompt
503Service busyRetry after a few seconds
504Processing timed outRetry; for images, switch to "async": true

For 429, 502, 503 and 504, retry with increasing backoff (for example 2 s, 5 s, 15 s). The server already retries internally before returning an error, so there is no need to retry aggressively. A failed task has status: "failed" and an error with the same meaning.

App integrations #

Any app that supports an OpenAI-compatible endpoint works. Choose the OpenAI provider (or “OpenAI-compatible” / “Custom”) and enter:

API base URL

https://muse.isemi.io/v1

API key

m2a-… — the key you received

AppNotes
LobeChatOpenAI provider → enter the API key and the API proxy URL (with /v1).
Open WebUIAdmin Settings → Connections → OpenAI API: URL with /v1.
Cherry StudioAdd an OpenAI-type provider; set API host to https://muse.isemi.io (the app adds /v1).
ChatGPT-Next-WebSet the custom endpoint to https://muse.isemi.io (without /v1).
n8n, Dify, LangChain…Use the OpenAI node / model and change the base URL.

If an app does not fetch the model list by itself, add muse-chat manually (and muse-image if the app supports image generation).

Limits & notes #

ItemLimit
Images per request (n)1–4
Reference images per requestUp to 4
Requested video duration1–60 seconds
Maximum processing timeChat 5 min · image 4 min · video 10 min (per attempt)
Wait for the first chat token45 seconds; after that the server retries automatically
  • Unsupported parameters are ignored rather than rejected, so clients that send newer OpenAI fields keep working.
  • Not supported yet: /v1/responses (use /v1/chat/completions), tool / function calling, mask for image edits, embeddings and audio.
  • Content that violates the content policy may be refused; the request then returns an error instead of a result, and is not charged.