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.
https://muse.isemi.io/v1Quickstart #
- Buy credit with PayPal or a card and get an API key (
m2a-…) instantly. - Install the OpenAI SDK:
pip install openaiornpm install openai. - 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:
Authorization: Bearer m2a-your-key
# or
X-Api-Key: m2a-your-keyA 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.
| Model | Kind | Endpoint | Capabilities |
|---|---|---|---|
muse-chat | Chat | /v1/chat/completions | Multi-turn chat, system prompts, streaming, image input |
muse-image | Image | /v1/images/generations/v1/images/edits | Text-to-image, reference images (up to 4), transparent background |
muse-video | Video | /v1/videos | Text-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 send | Served by |
|---|---|
gpt-4o · gpt-4o-mini · gpt-4.1 · gpt-5 · claude-sonnet-4 · deepseek-chat | muse-chat |
dall-e-3 · gpt-image-1 | muse-image |
sora | muse-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.
| Model | Price | Charged on |
|---|---|---|
muse-image | $0.015 per image | Each generated image; n images cost n × the price. Transparent background costs nothing extra. |
muse-video | $0.006 per second | The 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_usdfor chat,cost_usdfor 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 #
Compatible with OpenAI's client.chat.completions.create(), both streaming and non-streaming.
Parameters
muse-chat or a compatible name.
Default: muse-chat
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).
Return the reply in chunks over Server-Sent Events.
Default: false
{"include_usage": true} adds a final chunk with usage (including cost_usd).
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.
Accepted for compatibility but currently have no effect.
Response
{
"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,….
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 #
Compatible with client.images.generate(). Generates images from a prompt, optionally with reference images.
Parameters
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”).
Default: muse-image
Number of images to create, 1 to 4. Each image is billed.
Default: 1
Aspect ratio, for example 1:1, 16:9, 9:16, 4:3.
url returns a download link; b64_json returns the image base64-encoded inside the response.
Default: url
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.
One or up to 4 reference images: data URL, http(s) URL or a base64 string.
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"}'
{
"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 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.
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) #
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.
1 to 4 image files.
Describes the image to create from the references.
Same as image generation.
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 #
Video generation always runs as a task: POST returns a task right away, then poll GET /v1/videos/{id} until it finishes.
Parameters
Describes the video content.
Default: muse-video
Aspect ratio, for example 16:9 or 9:16.
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
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"])
{
"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:
task_…, used for polling.
image.task or video.
Estimated progress, 0–100.
Present when succeeded. Images: {"created", "data": [{"url"}]}. Video: {"url", "mime", "width", "height"} (width / height may be null).
Present when failed: {"message", "code"}.
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 #
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 #
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"])
{
"object": "balance",
"balance_usd": 12.34,
"currency": "USD",
"unlimited": false
}List 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.
{
"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": {
"message": "insufficient balance: this request costs $0.015000, balance is $0.004000; top up to continue",
"type": "insufficient_quota",
"code": "insufficient_balance"
}
}| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters (missing prompt, more than 4 images, model of the wrong kind…) | Fix the request according to message; do not retry it unchanged |
| 401 | API key missing, invalid or revoked | Check your key |
| 402 | Balance too low for this request (insufficient_balance); nothing was charged | Top up credit, then retry |
| 404 | Task or file not found | Check the ID; old tasks may have been cleaned up |
| 429 | Temporarily out of capacity | Retry after a few tens of seconds |
| 501 | Feature not supported yet | See limits |
| 502 | Generation failed | Retry; if it keeps failing with the same prompt, rephrase the prompt |
| 503 | Service busy | Retry after a few seconds |
| 504 | Processing timed out | Retry; 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
| App | Notes |
|---|---|
| LobeChat | OpenAI provider → enter the API key and the API proxy URL (with /v1). |
| Open WebUI | Admin Settings → Connections → OpenAI API: URL with /v1. |
| Cherry Studio | Add an OpenAI-type provider; set API host to https://muse.isemi.io (the app adds /v1). |
| ChatGPT-Next-Web | Set 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 #
| Item | Limit |
|---|---|
Images per request (n) | 1–4 |
| Reference images per request | Up to 4 |
| Requested video duration | 1–60 seconds |
| Maximum processing time | Chat 5 min · image 4 min · video 10 min (per attempt) |
| Wait for the first chat token | 45 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,maskfor 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.