Overview
Traffic to /v1/*, excluding task polling.
Requests over time
SuccessfulErrors (4xx/5xx or failed tasks)
Accounts
muse.ai accounts in the pool. Accounts that exhaust their quota return automatically after cooldown.
Bulk cookie import
Paste cookie strings here (one account per line, in the format name | hatch_sess=...; hatch_gw=...; or just a cookie string). POSTs to /admin/accounts/import.
Portal users
People registered on the public portal. Disabling a user immediately invalidates their sessions and API keys.
| Username | Status | API Keys | Last login |
|---|
API Keys
Keys used by clients to call /v1/*. The server stores only a hash—the key is shown once when issued.
| Name | Status | Total | 24h | Errors 24h | Last request |
|---|
Metrics come from the retained request log and exclude polls. Select a row to view requests for that key.
Requests
Log of every request to /v1/*. Select a row to view details.
| Time | Method | Path | Key | Status | Latency |
|---|
AI API Integration
Connect OpenAI-compatible clients and applications to this service.
Public API address
Use this Base URL in OpenAI-compatible applications. Do not use the admin page address.
Authentication header: Authorization: Bearer m2a-...
Verify connection
Paste a regular client API key. It stays only in this page and is never saved.
Use this when the full value of an existing key is no longer available.
Launch readiness
Quick configuration
Base URL
OpenAI compatible
API Key
m2a-...
Use a regular client key
Chat model
muse-chat
gpt-4o · gpt-4.1 · gpt-5
Media models
muse-image · muse-video
gpt-image-1 · sora
How a request is processed
1Client
Sends an OpenAI-compatible request with a client API key.
2Gateway
Authenticates, validates parameters, and resolves model aliases.
3Account pool
Selects a healthy upstream account and applies concurrency limits.
4AI provider
Runs chat, image, or video generation through the active driver.
5Normalized response
Returns OpenAI-style JSON, SSE streaming, task state, or a media URL.
Model routing
| Canonical model | Accepted aliases | Purpose | Execution |
|---|---|---|---|
| muse-chat | gpt-4o · gpt-4o-mini · gpt-4.1 · gpt-5 · claude-sonnet-4 · deepseek-chat | Chat and image understanding | Synchronous or SSE streaming |
| muse-image | dall-e-3 · gpt-image-1 | Image generation, references, and editing | Synchronous or asynchronous task |
| muse-video | sora | Text-to-video and first-frame image-to-video | Asynchronous task |
Aliases exist for client compatibility. The gateway resolves them to a canonical model; use the canonical model names in new integrations for clearer logs.
Code example
Supported endpoints
| Method | Endpoint | Purpose | Model | Execution |
|---|---|---|---|---|
| GET | /v1/models | List available models | — | Synchronous |
| POST | /v1/chat/completions | Chat completion | muse-chat | Synchronous or SSE streaming |
| POST | /v1/responses | Responses API | muse-chat | Synchronous or SSE streaming |
| POST | /v1/images/generations | Image generation | muse-image | Synchronous or asynchronous task |
| POST | /v1/images/edits | Multipart reference-image editing | muse-image | Synchronous |
| GET | /v1/images/generations/{task_id} | Read image task status and result | muse-image | Poll until completed |
| POST | /v1/videos | Video generation | muse-video | Asynchronous task |
| GET | /v1/videos/{task_id} | Read video progress and result URL | muse-video | Poll until completed |
| GET | /v1/media/{name} | Download generated media | — | Public unguessable URL |
Parameters and behavior
Chat / Responses
Use these endpoints for text conversations and image understanding.
- messages / input — required text or multimodal input
- stream: true — returns Server-Sent Events; clients must read until completion
- user — optional affinity key that helps reuse a warm upstream conversation
- tools / tool_choice — accepted by Chat Completions for compatibility but function calling is not provided by muse.ai
Images
Generate new images or use up to four references.
- prompt — required, non-empty prompt
- n — 1–4 images; response_format — url / b64_json
- image — data URL, public HTTP(S) URL, base64, or multipart file; maximum four references
- background: transparent — performs local background removal and returns PNG
- async: true — recommended for long jobs; poll the returned task ID
Videos
Video creation always returns a task immediately.
- prompt — required, non-empty prompt
- duration / seconds — 1–60 seconds when supported upstream
- image / input_reference — optional first-frame image as a data URL or public HTTP(S) URL
- status — queued → running → succeeded / failed
Compatibility limits
Unsupported behavior is rejected clearly instead of being silently faked.
- Responses function-call items are rejected because the current upstream has no function calling.
- Image masks/inpainting are not supported; uploaded images are treated as references.
- Sampling controls such as temperature are accepted for client compatibility but are not exposed by muse.ai.
- Unknown model names fall back to the canonical model for that endpoint; a known model of the wrong type returns 400.
Error diagnosis and recovery
| Status | Meaning | Resolution |
|---|---|---|
| 400 | Invalid parameter, empty prompt, unsupported input, or wrong model type | Compare the request with the parameter guide and request log details. |
| 401 | Client API key is missing, shortened, revoked, deleted, or incorrect | Create a new key, copy the complete m2a-... value once, and send it as a Bearer token. |
| 409 | The requested account operation conflicts with a running task | Wait for the current account request to finish, then retry. |
| 429 | Upstream account quota is exhausted | Add another account or wait for the account cooldown/quota reset. |
| 501 | The active provider driver does not implement this capability | Choose a supported endpoint or add a provider adapter with that capability. |
| 502 | The AI provider rejected or failed the request | Inspect the account state and request details; the gateway automatically fails over when safe. |
| 503 | No usable upstream account is currently available | Import, enable, renew, or re-authenticate an account in the account pool. |
| 504 | The upstream provider timed out | Retry later, use asynchronous media tasks, or add more healthy accounts. |
Recommended troubleshooting order
- Run the diagnostics above and confirm the gateway and provider driver are online.
- Test the complete client key against GET /v1/models.
- Confirm at least one upstream account is available, not disabled, invalid, or cooling down.
- Open Request logs, filter the status code, and inspect the exact error message.
- For image/video tasks, poll until succeeded or failed instead of treating the initial task response as final media.
Production integration advice
- Use generous timeouts and asynchronous tasks for image/video generation.
- Retry 502/504 with backoff; do not retry 400/401 until configuration is corrected.
- Keep client keys in server-side environment variables, never browser source code or public repositories.
- Monitor available accounts, quota, 5xx errors, p95 latency, and failed background tasks.
Provider architecture
Active provider muse.ai
Active driver: —
Capabilities: —
Adding future AI providers
The public OpenAI-compatible API, client keys, request log, task system, and media storage remain stable. A new provider is added behind the driver interface with its own account/session adapter and declared capabilities, so clients keep the same Base URL while routing rules evolve.
Security: Use a regular m2a-... client key here. Never put the administrator password, administrator session, or MUSE2API_ADMIN_KEY into an AI client.