Documentation Index
Fetch the complete documentation index at: https://mintlify.com/anil-matcha/open-generative-ai/llms.txt
Use this file to discover all available pages before exploring further.
Open Generative AI communicates with the Muapi.ai REST API through a JavaScript client library — muapi.js — which lives in packages/studio/src/muapi.js. Every image, video, audio, lip sync, clipping, and workflow generation in the studio is routed through this file’s named exports. Developers can import these functions directly into their own applications by depending on the studio package, giving them the same API surface that powers the studio UI.
Base URL
The base URL is selected automatically by muapi.js at runtime based on the JavaScript environment:
| Environment | Base URL | Why |
|---|
| Browser (HTTP/HTTPS) | /api | A Next.js proxy route re-issues the request server-side, bypassing the api.muapi.ai CORS restriction |
| Electron desktop app | https://api.muapi.ai | The renderer runs on file://, which is not HTTP, so requests go directly to the upstream |
| SSR / Node.js | https://api.muapi.ai | There is no window object in server-side rendering, so the upstream URL is used directly |
muapi.js:
const BASE_URL =
typeof window !== 'undefined' && window.location?.protocol?.startsWith('http')
? '/api'
: 'https://api.muapi.ai';
You do not need to set the base URL manually. Whether you are running the Next.js web version, the Electron desktop app, or calling the functions from server-side code, muapi.js picks the correct target automatically.
Submit-and-Poll Pattern
All AI generation endpoints on the Muapi.ai API are asynchronous. You submit a job and receive a request_id, then poll a separate result endpoint until the job finishes. muapi.js implements this pattern internally inside submitAndPoll and pollForResult, so callers just await a single function call — but understanding the underlying flow is useful when calling the API directly or debugging.
Submit the generation job
POST to https://api.muapi.ai/api/v1/{model-endpoint} with your prompt, parameters, and API key in the x-api-key header. The response is a JSON object containing a request_id (or id) that identifies the queued job.
Receive the request ID
The API immediately returns:{ "request_id": "abc123xyz..." }
Poll the result endpoint
GET https://api.muapi.ai/api/v1/predictions/{request_id}/result repeatedly, waiting 2 seconds between each attempt. The response includes a status field that reflects the current state of the job.
Read the output URL
When data.status (lowercased) is completed, succeeded, or success, the generation is done. The output URL is resolved by checking data.outputs?.[0], then data.url, then data.output?.url (in that order). If status is failed or error, throw immediately using data.error.
Polling limits
| Generation type | Max poll attempts | Max wait time |
|---|
Image generation (generateImage, generateI2I) | 60 | ~2 minutes |
| Video, audio, workflow, and all other functions | 900 | ~30 minutes |
Minimal JavaScript example
// Step 1 — Submit the job
const res = await fetch('https://api.muapi.ai/api/v1/flux-schnell-image', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': YOUR_API_KEY
},
body: JSON.stringify({ prompt: 'a serene mountain lake at sunrise' })
});
const { request_id } = await res.json();
// Steps 2–4 — Poll until done
let output;
while (true) {
await new Promise(r => setTimeout(r, 2000));
const poll = await fetch(
`https://api.muapi.ai/api/v1/predictions/${request_id}/result`,
{ headers: { 'x-api-key': YOUR_API_KEY } }
);
const data = await poll.json();
const status = data.status?.toLowerCase();
if (['completed', 'succeeded', 'success'].includes(status)) {
output = data.outputs?.[0] || data.url || data.output?.url;
break;
}
if (['failed', 'error'].includes(status)) {
throw new Error(data.error || 'Generation failed');
}
}
console.log('Generated output URL:', output);
When using the muapi.js functions (e.g. generateImage, generateVideo), the entire submit-and-poll loop runs inside the function call. You await the result and receive { ...pollData, url: outputUrl } directly — no manual polling required.
Available API Functions
The following named exports are available from packages/studio/src/muapi.js (or from the studio package). All generation functions accept (apiKey, params) and internally handle the submit-and-poll lifecycle.
Generation functions — all accept (apiKey, params) and run the full submit-and-poll lifecycle internally:
| Function | Description |
|---|
generateImage | Text-to-image generation (50+ models). Also accepts an image_url or images_list for image-conditioned models. Max 60 poll attempts. |
generateI2I | Image-to-image transformation. Accepts one or more reference images; uses the model’s configured imageField to route them correctly. Max 60 poll attempts. |
generateVideo | Text-to-video generation (40+ models). Supports aspect ratio, duration, resolution, quality, and optional image_url. Max 900 poll attempts. |
generateI2V | Image-to-video animation. Animates a start-frame image (or image list) into a video. Supports an optional last_image for models that accept end-frame conditioning. Max 900 poll attempts. |
generateMarketingStudioAd | Marketing video generation using omni-reference models. Accepts prompt, aspect_ratio, duration, images_list, and video_files. Max 900 poll attempts. |
processV2V | Video-to-video transformation. Routes the video_url (and optional image_url or prompt) through the model’s configured fields. Max 900 poll attempts. |
processRecast | Video recast / style transfer. Accepts video_url, optional image_url, prompt, and aspect_ratio. Max 900 poll attempts. |
processLipSync | Audio-driven lip sync. Accepts audio_url and either an image_url (portrait) or video_url (existing video). Max 900 poll attempts. |
generateAudio | Audio generation. Passes all non-internal params through to the model endpoint. Max 900 poll attempts. |
runClipping | AI video clipping and highlight extraction. Accepts video_url, num_highlights, aspect_ratio, and return_coordinates_only. Endpoint: ai-clipping. Max 900 poll attempts. |
runMotionGraphics | Motion graphics generation from a text prompt. Accepts prompt, aspect_ratio, and duration_seconds. Endpoint: motion-graphics. Max 900 poll attempts. |
runMotionGraphicsEdit | Edit an existing motion graphics result. Accepts request_id, edit_prompt, aspect_ratio, and duration_seconds. Endpoint: motion-graphics-edit. Max 900 poll attempts. |
| Function | Description |
|---|
uploadFile | Upload a reference image or file via multipart/form-data to POST /api/v1/upload_file. Returns the hosted file URL as a string. Accepts an optional onProgress callback. |
| Function | Description |
|---|
getUserBalance | Fetch the current API credit balance. Returns the full JSON response from GET /api/v1/account/balance. |
calculateDynamicCost | Calculate the credit cost for a given task before running it. POSTs to POST /api/v1/app/calculate_dynamic_cost. |
| Function | Description |
|---|
getTemplateWorkflows | Fetch available template workflows from GET /workflow/get-template-workflows. |
getUserWorkflows | Fetch the authenticated user’s saved workflow definitions from GET /workflow/get-workflow-defs. |
getPublishedWorkflows | Fetch publicly published workflows from GET /workflow/get-published-workflows. |
getWorkflowData | Fetch the full definition of a single workflow by ID from GET /workflow/get-workflow-def/{workflowId}. |
createWorkflow | Create a new workflow definition via POST /workflow/create. |
updateWorkflowName | Rename a workflow via POST /workflow/update-name/{workflowId}. |
deleteWorkflow | Delete a workflow definition via DELETE /workflow/delete-workflow-def/{workflowId}. |
getWorkflowInputs | Fetch the API-exposed input schema for a workflow from GET /workflow/{workflowId}/api-inputs. |
executeWorkflow | Execute a saved workflow by workflowId. POSTs to /workflow/{workflowId}/api-execute with an inputs object, then polls /workflow/run/{runId}/api-outputs until completion. |
getAllNodeSchemas | Fetch all node schemas for a workflow from GET /workflow/{workflowId}/node-schemas. |
getNodeSchemas | Fetch API-exposed node schemas for a workflow from GET /workflow/{workflowId}/api-node-schemas. |
runSingleNode | Execute a single node within a workflow via POST /workflow/{workflowId}/node/{nodeId}/run. |
deleteNodeRun | Delete a node run record via DELETE /workflow/node-run/{nodeRunId}. |
getNodeStatus | Check the status of a workflow run via GET /workflow/run/{runId}/status. |
| Function | Description |
|---|
getTemplateAgents | Fetch available template agents from GET /agents/templates/agents. |
getUserAgents | Fetch the authenticated user’s agents from GET /agents/user/agents. |
getPublishedAgents | Fetch featured/published agents from GET /agents/featured/agents. |
getUserConversations | Fetch the user’s conversation history across all agents from GET /agents/user/conversations. |
| Function | Description |
|---|
handleProxyRequest | Low-level proxy helper that forwards a request to a given prefix/path on the upstream API, injecting x-api-key. Used by server-side routes. |
handleServerSideProxy | Higher-level Next.js route handler that extracts the path from params.path, reads the request body, and delegates to handleProxyRequest. |
| Function | Description |
|---|
registerAppInterest | Register user interest in an app feature via POST /app/interest. |
getAppInterests | Retrieve the current user’s registered app interests from GET /app/interests. |
Error Handling
muapi.js applies a consistent error strategy across all functions:
- 4xx errors (client errors) throw immediately with the HTTP status and response body included in the error message.
- 5xx errors (server errors) are silently skipped during polling and retried on the next interval.
- 401 / 403 errors additionally dispatch a
muapi:auth-required custom event on window (when available), which the studio UI listens to in order to show the API key entry modal.
window.addEventListener('muapi:auth-required', (event) => {
console.log('Auth failed:', event.detail.status, event.detail.message);
// Show your API key UI here
});
- If
submitAndPoll or pollWorkflowResult exhausts all polling attempts without a terminal status, they throw: 'Generation timed out after polling.'
