MuAPI

https://muapi.ai/docs
Admin
MuAPI is a high-performance AI API provider offering curated access to industry-leading generation...
Tokens:76,810
Snippets:575
Trust Score:6.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /agent-skills Response Example

Source: https://muapi.ai/docs/design-agent-api

Example response for the GET /agent-skills endpoint, showing a JSON array of skill objects.

```json
[
  {
    "name": "fashion-try-on",
    "description": "Virtually try on different outfits...",
    "inputs": ["person_image", "clothing_image"],
    "trigger_keywords": ["fashion try on", "virtual fitting room", ...],
    "estimated_credits": 150
  },
  {
    "name": "action-figure-generator",
    "description": "Convert a photo of a person into a custom 3D action figure...",
    ...
  }
]
```

--------------------------------

### List Skills - Response (200 OK)

Source: https://muapi.ai/docs/agents

Example response from the GET /agents/skills endpoint. Returns an array of skill objects, each with an id, aitask_id, name, and description.

```json
[
  {
    "id": "web_search",
    "aitask_id": 101,
    "name": "Web Search",
    "description": "Search the internet for information."
  },
  {
    "id": "code_exec",
    "aitask_id": 102,
    "name": "Code Execution",
    "description": "Execute python code."
  }
]
```

--------------------------------

### List All Recipes - Response 200 OK

Source: https://muapi.ai/docs/agents

Example JSON response from GET https://api.muapi.ai/api/v1/agent-skills. No authentication required. Shows a skill object with name, description, triggers, inputs, estimated_credits, and url.

```json
{
  "skills": [
    {
      "name": "storyboard",
      "description": "Generate N keyframes for a short story or scene sequence (image only, no video).",
      "triggers": ["storyboard", "keyframes", "scene sequence"],
      "inputs": ["premise", "scenes", "style"],
      "estimated_credits": 0,
      "url": "/api/v1/agent-skills/storyboard"
    }
  ]
}
```

--------------------------------

### Install MuAPI Agent Skills via npx skills

Source: https://muapi.ai/docs/agent-skills

Install MuAPI Agent Skills from the SamurAIGPT/Generative-Media-Skills registry. Use --all to install every skill, --skill to install a specific one, or --list to see available skills.

```bash
# Install all MuAPI skills via the skills registry
npx skills add SamurAIGPT/Generative-Media-Skills --all

# Or install a specific skill
npx skills add SamurAIGPT/Generative-Media-Skills --skill muapi-media-generation

# List available skills
npx skills add SamurAIGPT/Generative-Media-Skills --list
```

--------------------------------

### Fetch a Recipe Body - Response 200 OK

Source: https://muapi.ai/docs/agents

Example JSON response from GET https://api.muapi.ai/api/v1/agent-skills/{name}. No authentication required. Returns the full markdown body for the recipe, which the agent reads and uses to make underlying muapi tool calls.

```json
{
  "name": "storyboard",
  "description": "...",
  "inputs": { "premise": { "type": "text", "required": true, "description": "..." }, "scenes": { "type": "int", "default": 6 } },
  "trigger_keywords": ["storyboard", "keyframes"],
  "estimated_credits": 0,
  "body": "# Storyboard\n\nStep 1: ...\nStep 2: ...\n"
}
```

--------------------------------

### Install muapi-langchain from source

Source: https://muapi.ai/docs/langchain

Install the muapi-langchain package from the muapi-cli repository. The optional second command installs dependencies for the Deep Agents recipe.

```bash
pip install "git+https://github.com/SamurAIGPT/muapi-cli.git#subdirectory=integrations/langchain"

# Optional: for the Deep Agents recipe below
pip install "deepagents langgraph langchain-openai"
```

--------------------------------

### Seedance 2.0 Image-to-Video prompt example

Source: https://muapi.ai/docs/comfyui

Example prompt for the Seedance 2.0 Image-to-Video node. Reference up to 9 images using @image1...@image9 placeholders.

```text
The cat in @image1 walks gracefully through a sunlit garden.
@image1 transforms into @image2 with a smooth dissolve.
```

--------------------------------

### Install and configure muapi CLI

Source: https://muapi.ai/docs/mcp

Install the muapi CLI globally and configure your API key. Run these commands before setting up the MCP server.

```bash
npm install -g muapi-cli

muapi auth configure --api-key "YOUR_KEY"
```

--------------------------------

### Self-host muapi-mcp-server with FastAPI

Source: https://muapi.ai/docs/mcp

Clone the muapi-mcp-server repository, install dependencies, and run the FastAPI server with your MUAPI_API_KEY. This starts a standalone MCP server instance for teams that want to host their own.

```bash
git clone https://github.com/SamurAIGPT/muapi-mcp-server.git
cd muapi-mcp-server
pip install fastapi uvicorn requests pydantic
MUAPI_API_KEY=your_key python mcp_server.py
```

--------------------------------

### List User Agents - Response (200 OK)

Source: https://muapi.ai/docs/agents

Example response from the GET /agents/user/agents endpoint. Returns an array of agent objects, each with an id and name, with additional fields omitted for brevity.

```json
[
  {
    "id": "agent_12345",
    "name": "Research Assistant",
    ...
  },
  {
    "id": "agent_67890",
    "name": "Coding Bot",
    ...
  }
]
```

--------------------------------

### Install muapi-comfyui manually

Source: https://muapi.ai/docs/comfyui

Manual installation for the muapi-comfyui node pack. Run these commands from the ComfyUI root directory to clone the repository and install its dependencies.

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/SamurAIGPT/muapi-comfyui
pip install -r muapi-comfyui/requirements.txt
```

--------------------------------

### Install seedance2-comfyui manually

Source: https://muapi.ai/docs/comfyui

Manual installation for the seedance2-comfyui node pack. Run these commands from the ComfyUI root directory to clone the repository and install its dependencies.

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/Anil-matcha/seedance2-comfyui
pip install -r seedance2-comfyui/requirements.txt
```

--------------------------------

### Configure MuAPI API Key with setup.sh

Source: https://muapi.ai/docs/agent-skills

Configure your MuAPI API key by running the setup script. Replace YOUR_MUAPI_KEY with the key obtained from https://muapi.ai/dashboard.

```bash
# Get your key at https://muapi.ai/dashboard
bash core/platform/setup.sh --add-key "YOUR_MUAPI_KEY"
```

--------------------------------

### Quick Create Agent Response

Source: https://muapi.ai/docs/agents

Example 200 OK response from the quick-create endpoint. Contains the generated agent's id, name, system_prompt, and skills array.

```json
{
  "id": "agent_abc123",
  "name": "Streetware Guru",
  "system_prompt": "You are an expert brand designer...",
  "skills": [...]
}
```

--------------------------------

### Install MuAPI CLI with npm, pip, or npx

Source: https://muapi.ai/docs/cli

Install the MuAPI CLI globally via npm or pip, or run it without installing using npx. The npm method is recommended and does not require Python.

```bash
# npm (recommended — no Python required)
npm install -g muapi-cli

# pip
pip install muapi-cli

# or run without installing
npx muapi-cli --help
```

--------------------------------

### Image-to-Video workflow

Source: https://muapi.ai/docs/comfyui

Example workflow for image-to-video generation using the MuAPI nodes.

```text
[Load Image] → image_1 → [🎬 MuAPI Image-to-Video] → video_url → [🎬 MuAPI Save Video]
```

--------------------------------

### Text-to-Video workflow

Source: https://muapi.ai/docs/comfyui

Example workflow for text-to-video generation using the MuAPI nodes.

```text
[🌱 Text-to-Video] → video_url → [🌱 Save Video] → frames → [Preview Image]
```

--------------------------------

### Install muapi-comfyui node pack via Git URL

Source: https://muapi.ai/docs/quick-start

Install the official muapi-comfyui node pack to run MuAPI models inside ComfyUI visual workflows. Use the provided Git URL in ComfyUI Manager.

```bash
# Install via ComfyUI Manager → Install via Git URL
https://github.com/SamurAIGPT/muapi-comfyui
```

--------------------------------

### CLI Commands for Video Generation

Source: https://muapi.ai/docs/kling

Shows how to generate videos from the command line using the muapi CLI, with examples for text-to-video and image-to-video.

```bash
# Text-to-video
muapi video generate "A astronaut floating in space, Earth visible below" --model kling-master

# Image-to-video
muapi video from-image portrait.jpg "Person blinks and looks away" --model kling-pro
```

--------------------------------

### GET /jobs/{job_id}/events - 200 OK response

Source: https://muapi.ai/docs/design-agent-api

Example response for polling job events. Shows a processing job with text, plan_propose, and tool_result events, including the cursor for the next poll.

```json
{
  "job_id": "job_def456",
  "status": "processing",
  "error": null,
  "approved": null,
  "approval_requested": false,
  "cursor": 42,
  "events": [
    {
      "id": 38,
      "type": "text",
      "payload": { "content": "I'll create your action figure now..." },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:06Z"
    },
    {
      "id": 39,
      "type": "plan_propose",
      "payload": {
        "title": "Action Figure Generation Plan",
        "nodes": [
          { "tool": "edit_image", "model": "nano-banana-2-edit", "credits": 80 }
        ],
        "total_credits": 80
      },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:07Z"
    },
    {
      "id": 42,
      "type": "tool_result",
      "payload": {
        "name": "edit_image",
        "result": {
          "url": "https://cdn.muapi.ai/...",
          "source_asset_id": "asset_1"
        },
        "asset": {
          "asset_label": "asset_2",
          "kind": "image",
          "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_2.webp"
        }
      },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:45Z"
    }
  ],
  "done": true
}
```

--------------------------------

### Enhancement pipeline workflow

Source: https://muapi.ai/docs/comfyui

Example workflow for an enhancement pipeline: background removal followed by upscaling.

```text
[Load Image] → [✨ MuAPI Image Enhance (bg-remove)] → [✨ MuAPI Image Enhance (upscale)] → [Preview Image]
```

--------------------------------

### Install n8n-nodes-muapi via npm

Source: https://muapi.ai/docs/n8n

Install the MuAPI n8n community node package on a self-hosted n8n instance. Requires npm access to the user's n8n directory and systemctl privileges to restart the n8n service.

```bash
cd ~/.n8n
npm install n8n-nodes-muapi
sudo systemctl restart n8n
```

--------------------------------

### Install Shell Completions for MuAPI CLI

Source: https://muapi.ai/docs/cli

Enable shell autocompletion for bash, zsh, or fish. Run the appropriate command for your shell.

```bash
muapi --install-completion bash
muapi --install-completion zsh
muapi --install-completion fish
```

--------------------------------

### Error Response JSON Example

Source: https://muapi.ai/docs/design-agent-api

Example of a standard error response body returned with HTTP error status codes.

```json
{
  "detail": "Session not found"
}
```

--------------------------------

### List session assets response

Source: https://muapi.ai/docs/design-agent-api

Example 200 OK response for retrieving all assets of a session. Sorted oldest first. Each asset includes its label, type, CDN URL, source tool, generating model, prompt, and creation timestamp; fields may be null.

```json
[
  {
    "asset_label": "asset_1",
    "kind": "image",
    "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_1.webp",
    "source_tool": "upload",
    "model": null,
    "prompt": null,
    "created_at": "2026-05-08T07:05:00Z"
  },
  {
    "asset_label": "asset_2",
    "kind": "image",
    "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_2.webp",
    "source_tool": "generate_image",
    "model": "nano-banana-2",
    "prompt": "A cinematic portrait of a woman in a black suit",
    "created_at": "2026-05-08T07:12:00Z"
  }
]
```

--------------------------------

### GET /sessions response

Source: https://muapi.ai/docs/design-agent-api

Response for GET /sessions. Returns a list of sessions ordered by most recently updated. Each session includes id, name, credits_spent, asset_count, and timestamps.

```json
[
  {
    "id": "sess_abc123",
    "name": "My Fashion Shoot",
    "credits_spent": 120,
    "asset_count": 5,
    "created_at": "2026-05-08T07:00:00Z",
    "updated_at": "2026-05-08T09:30:00Z"
  }
]
```

--------------------------------

### GET /api/app/get_file_upload_url

Source: https://muapi.ai/docs/design-agent-api

Gets a signed upload URL for direct-to-S3 uploads. This endpoint is part of the Dashboard API (separate prefix).

```APIDOC
## GET /api/app/get_file_upload_url

### Description
Get a signed upload URL for direct-to-S3 uploads. This endpoint is part of the Dashboard API (separate prefix).

### Method
GET

### Endpoint
/api/app/get_file_upload_url

### Parameters
#### Query Parameters
- **filename** (string) - Required - The name of the file to upload.

### Headers
- **x-api-key** (string) - Required - The API key for the Dashboard API.

### Response
#### Success Response (200)
- **url** (string) - The S3 upload URL.
- **fields** (object) - The form fields to include in the upload.
  - **key** (string) - The S3 object key.
  - **AWSAccessKeyId** (string) - The AWS access key ID.
  - **policy** (string) - The upload policy.
  - **signature** (string) - The signature.

#### Response Example
```json
{
  "url": "https://s3.amazonaws.com/muapi-uploads/...",
  "fields": {
    "key": "uploads/user_123/abc/my-photo.jpg",
    "AWSAccessKeyId": "...",
    "policy": "...",
    "signature": "..."
  }
}
```
```

--------------------------------

### CLI Interactive Workflow Run

Source: https://muapi.ai/docs/workflows

For a guided CLI experience, use the interactive run tool which prompts for all required inputs.

```bash
muapi workflow run-interactive <workflow_id>
```

--------------------------------

### GET /sessions

Source: https://muapi.ai/docs/design-agent-api

Lists all sessions belonging to the authenticated user, ordered by most recently updated.

```APIDOC
## GET /sessions

### Description
List all sessions belonging to the authenticated user, ordered by most recently updated.

### Method
GET

### Endpoint
/sessions

### Parameters
None

### Response
#### Success Response (200)
- **id** (string) - Unique session identifier
- **name** (string) - Human-readable session name
- **credits_spent** (number) - Total credits consumed in this session
- **asset_count** (number) - Total number of generated/uploaded assets
- **created_at** (ISO 8601) - Session creation timestamp
- **updated_at** (ISO 8601) - Last activity timestamp

#### Response Example
```json
[
  {
    "id": "sess_abc123",
    "name": "My Fashion Shoot",
    "credits_spent": 120,
    "asset_count": 5,
    "created_at": "2026-05-08T07:00:00Z",
    "updated_at": "2026-05-08T09:30:00Z"
  }
]
```
```

--------------------------------

### GET /sessions/{session_id}/assets

Source: https://muapi.ai/docs/design-agent-api

Retrieves all assets registered for a session, sorted by creation time (oldest first).

```APIDOC
## GET /sessions/{session_id}/assets

### Description
Retrieve all assets registered for a session, sorted by creation time (oldest first).

### Method
GET

### Endpoint
/sessions/{session_id}/assets

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **asset_label** (string) - Agent-addressable label (e.g. `asset_1`). Used in chat to reference specific assets.
- **kind** (string) - `"image"` | `"video"` | `"audio"`
- **url** (string) - CDN URL of the media file
- **source_tool** (string) - How the asset was created: `"upload"`, `"generate_image"`, `"edit_image"`, `"image_to_video"`, etc.
- **model** (string | null) - Model used to generate the asset
- **prompt** (string | null) - Prompt used when generating
- **created_at** (ISO 8601) - Asset registration timestamp

#### Response Example
```json
[
  {
    "asset_label": "asset_1",
    "kind": "image",
    "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_1.webp",
    "source_tool": "upload",
    "model": null,
    "prompt": null,
    "created_at": "2026-05-08T07:05:00Z"
  },
  {
    "asset_label": "asset_2",
    "kind": "image",
    "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_2.webp",
    "source_tool": "generate_image",
    "model": "nano-banana-2",
    "prompt": "A cinematic portrait of a woman in a black suit",
    "created_at": "2026-05-08T07:12:00Z"
  }
]
```
```

--------------------------------

### GET /sessions/{session_id}/messages

Source: https://muapi.ai/docs/design-agent-api

Retrieves the full persisted chat history for a given session.

```APIDOC
## GET /sessions/{session_id}/messages

### Description
Retrieve the full persisted chat history for a session.

### Method
GET

### Endpoint
/sessions/{session_id}/messages

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
Returns an array of message objects. Each message contains:
- **role** (string) - The role of the message sender (e.g., "user" or "assistant").
- **content** (string) - The text content of the message.
- **attachments** (array) - Optional. List of attachment objects, each with `asset_label`, `url`, and `kind`.
- **timestamp** (string) - ISO 8601 timestamp of the message.
- **skill_name** (string) - Optional. The name of the skill that generated the message.
- **events** (array) - Optional. List of event objects (e.g., tool calls and results).

#### Response Example
```json
[
  {
    "role": "user",
    "content": "Generate a 3D action figure of me in a doctor outfit",
    "attachments": [
      { "asset_label": "asset_1", "url": "...", "kind": "image" }
    ],
    "timestamp": "2026-05-08T07:10:00Z",
    "skill_name": "action-figure-generator"
  },
  {
    "role": "assistant",
    "content": "I'll create your action figure right away!",
    "events": [
      { "type": "tool_call", "name": "edit_image", "args": { ... } },
      { "type": "tool_result", "name": "edit_image", "result": { ... }, "asset": { ... } }
    ],
    "timestamp": "2026-05-08T07:10:05Z"
  }
]
```
```

--------------------------------

### GET /agent-skills

Source: https://muapi.ai/docs/design-agent-api

Retrieves a list of all available expert skill recipes. The response includes skill names, descriptions, required inputs, trigger keywords, and estimated credit costs.

```APIDOC
## GET /agent-skills

### Description
List all available expert skill recipes loaded from `agent/skills/*.skill.md`.

### Method
GET

### Endpoint
/agent-skills

### Response
#### Success Response (200)
- **name** (string) - The skill name.
- **description** (string) - A brief description of the skill.
- **inputs** (array of strings) - Required input names for the skill.
- **trigger_keywords** (array of strings) - Keywords that trigger the skill.
- **estimated_credits** (number) - Estimated credit cost for using the skill.

#### Response Example
```json
[
  {
    "name": "fashion-try-on",
    "description": "Virtually try on different outfits...",
    "inputs": ["person_image", "clothing_image"],
    "trigger_keywords": ["fashion try on", "virtual fitting room", ...],
    "estimated_credits": 150
  },
  {
    "name": "action-figure-generator",
    "description": "Convert a photo of a person into a custom 3D action figure...",
    ...
  }
]
```
```

--------------------------------

### Step 1 - Get a Signed Upload URL

Source: https://muapi.ai/docs/design-agent-api

Requests a signed upload URL from the Dashboard API (separate prefix). Requires the x-api-key header with MUAPIAPP_API_KEY. The response contains the S3 URL and form fields for the upload.

```http
GET /api/app/get_file_upload_url?filename=my-photo.jpg
x-api-key: {MUAPIAPP_API_KEY}
```

```json
{
  "url": "https://s3.amazonaws.com/muapi-uploads/...",
  "fields": {
    "key": "uploads/user_123/abc/my-photo.jpg",
    "AWSAccessKeyId": "...",
    "policy": "...",
    "signature": "..."
  }
}
```

--------------------------------

### Quick Start: Discover and Generate with muapi_select and muapi_generate

Source: https://muapi.ai/docs/langchain

Shows the full quick-start flow: first call muapi_select to rank candidate models for an intent (free, no credits), then call muapi_generate to produce an asset. Both tools are plain @tool-decorated functions usable in any LangChain agent framework.

```python
from muapi_langchain import muapi_select, muapi_generate
import json

# Discover candidates (free — no credits spent)
result = muapi_select.invoke({
    "intent": "cinematic product photo of a sneaker",
    "kind": "image",
    "tier": "best",
    "limit": 3,
})
print(json.loads(result)["models"])

# Generate
out = muapi_generate.invoke({
    "prompt": "A glossy sneaker on a wet street, neon-lit night",
    "kind": "image",
    "tier": "best",
})
print(json.loads(out)["url"])
```

--------------------------------

### Get Agent Details - Response (404 Not Found)

Source: https://muapi.ai/docs/agents

Example error response from the GET /agents/{agent_id} endpoint when the agent does not exist. Returns a JSON object with a 'detail' field.

```json
{
  "detail": "Agent not found"
}
```

--------------------------------

### Suggest Agent Configuration - Response (200 OK)

Source: https://muapi.ai/docs/agents

Example response from the /agents/suggest endpoint. Contains the suggested agent name, description, system prompt, and recommended skill IDs.

```json
{
  "name": "Python Wizard",
  "description": "An expert Python developer focused on writing clean, efficient code.",
  "system_prompt": "You are an expert Python developer...",
  "recommended_skill_ids": ["python_exec", "file_io"]
}
```

--------------------------------

### GET /sessions/{session_id}/jobs

Source: https://muapi.ai/docs/design-agent-api

Lists the 20 most recent jobs for a session. Useful for detecting and resuming in-flight jobs after a page refresh.

```APIDOC
## GET /sessions/{session_id}/jobs

### Description
List the 20 most recent jobs for a session. Useful for detecting and resuming in-flight jobs after a page refresh.

### Method
GET

### Endpoint
/sessions/{session_id}/jobs

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **id** (string) - The job ID.
- **status** (string) - The job status (e.g., "processing").
- **user_message** (string) - The user message associated with the job.
- **error** (string|null) - Error message if any, otherwise null.
- **created_at** (string) - Timestamp when the job was created.
- **completed_at** (string|null) - Timestamp when the job was completed, or null if not completed.

#### Response Example
```json
[
  {
    "id": "job_def456",
    "status": "processing",
    "user_message": "Create an action figure of me",
    "error": null,
    "created_at": "2026-05-08T07:10:00Z",
    "completed_at": null
  }
]
```
```

--------------------------------

### Add muapi MCP server to Claude Code

Source: https://muapi.ai/docs/mcp

Register the muapi MCP server with Claude Code for the current project. After running, start a new session and verify with `claude mcp list` to see `Type: stdio` and `✔ Connected`.

```bash
claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve
```

--------------------------------

### List all models with pricing

Source: https://muapi.ai/docs/pricing

Fetches the live pricing catalog for all models. The response includes model details such as cost, currency, dynamic pricing flag, and endpoints. Optional query filters are available: ?category=Text+to+Video, ?family=flux, ?group_of=image-generation. The response also includes fields like is_enabled, is_coming_soon, input_fields, and required_fields.

```bash
curl https://api.muapi.ai/api/v1/models
```

```json
{
  "models": [
    {
      "name": "flux-dev",
      "description": "High-quality text-to-image FLUX model.",
      "category": "Text to Image",
      "family": "flux",
      "group_of": "image-generation",
      "cost": 0.025,
      "cost_currency": "USD",
      "cost_strategy": "fixed_cost",
      "dynamic_pricing": false,
      "endpoint": "/api/v1/flux-dev",
      "estimate_endpoint": null
    },
    {
      "name": "veo3-fast",
      "category": "Text to Video",
      "cost": 0.4,
      "cost_currency": "USD",
      "dynamic_pricing": true,
      "endpoint": "/api/v1/veo3-fast",
      "estimate_endpoint": "/api/v1/models/veo3-fast/estimate-cost"
    }
  ],
  "total": 142,
  "currency": "USD"
}
```

--------------------------------

### GET /jobs/{job_id}/events

Source: https://muapi.ai/docs/design-agent-api

Polls for events of a background job. Returns a list of events and a done flag. Use the since query parameter to fetch events after a cursor.

```APIDOC
## GET /jobs/{job_id}/events

### Description
Polls for events of a background job. Returns a list of events and a done flag. Use the since query parameter to fetch events after a cursor.

### Method
GET

### Endpoint
/jobs/{job_id}/events

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The identifier of the background job.

#### Query Parameters
- **since** (integer) - Optional - Cursor for fetching events after a certain point.

### Response
#### Success Response (200)
- **events** (array) - List of events.
- **done** (boolean) - Indicates whether the job is complete.

#### Response Example
{
  "events": [],
  "done": false
}
```

--------------------------------

### Authenticate and Generate Media with MuAPI CLI

Source: https://muapi.ai/docs/cli

Quick start commands to authenticate with MuAPI and generate media. Use `muapi auth login` with email and password, or `muapi auth configure` with an existing API key. Then generate images, videos, and audio with the specified models.

```bash
# Authenticate
muapi auth login --email you@example.com --password "..."

# Or configure an existing API key
muapi auth configure --api-key "YOUR_KEY"

# Generate Media
muapi image generate "a cyberpunk city at night" --model flux-dev
muapi video generate "a dog running on a beach" --model kling-master
muapi audio create "upbeat lo-fi hip hop for studying"
```

--------------------------------

### GET /jobs/{job_id}/events

Source: https://muapi.ai/docs/design-agent-api

This endpoint allows clients to poll for streaming events produced by the agent during a job turn. It supports cursor-based pagination to retrieve only new events since the last poll.

```APIDOC
## GET /jobs/{job_id}/events

### Description
Poll for streaming events produced by the agent during a job turn. Use cursor-based pagination to receive only new events since the last poll.

### Method
GET

### Endpoint
/jobs/{job_id}/events

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job.

#### Query Parameters
- **since** (integer) - Optional - Return only events with `id > since`. Start at `0` for a fresh poll. Default: `0`.
- **limit** (integer) - Optional - Max events to return per call (max 1000). Default: `200`.

### Response
#### Success Response (200)
- **job_id** (string) - The job identifier.
- **status** (string) - Current state: `pending`, `processing`, `completed`, `failed`.
- **error** (string) - Error message (if status is `failed`).
- **approved** (boolean | null) - `true` if approved, `false` if rejected, `null` if pending.
- **approval_requested** (boolean) - `true` if the agent is currently waiting for user confirmation.
- **cursor** (number) - Cursor for the next poll.
- **events** (object[]) - List of events since the last poll.
- **done** (boolean) - `true` if job has finished.

#### Response Example
```json
{
  "job_id": "job_def456",
  "status": "processing",
  "error": null,
  "approved": null,
  "approval_requested": false,
  "cursor": 42,
  "events": [
    {
      "id": 38,
      "type": "text",
      "payload": { "content": "I'll create your action figure now..." },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:06Z"
    },
    {
      "id": 39,
      "type": "plan_propose",
      "payload": {
        "title": "Action Figure Generation Plan",
        "nodes": [
          { "tool": "edit_image", "model": "nano-banana-2-edit", "credits": 80 }
        ],
        "total_credits": 80
      },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:07Z"
    },
    {
      "id": 42,
      "type": "tool_result",
      "payload": {
        "name": "edit_image",
        "result": {
          "url": "https://cdn.muapi.ai/...",
          "source_asset_id": "asset_1"
        },
        "asset": {
          "asset_label": "asset_2",
          "kind": "image",
          "url": "https://cdn.muapi.ai/sessions/sess_xyz/asset_2.webp"
        }
      },
      "job_id": "job_def456",
      "created_at": "2026-05-08T07:10:45Z"
    }
  ],
  "done": true
}
```

### Event Types Reference
- **text** - Streaming agent text (chat bubble content). Key payload fields: `content: string`.
- **info** - Status message (e.g. "Waiting for approval..."). Key payload fields: `content: string`, `needs_approval: boolean`.
- **error** - An error occurred. Key payload fields: `message: string`.
- **tool_call** - Agent is about to call a tool. Key payload fields: `name: string`, `args: object`.
- **tool_result** - A tool call completed. Contains the new asset. Key payload fields: `name: string`, `result: object`, `asset: AssetObject`.
- **plan_propose** - Agent proposed a generation plan pending approval. Key payload fields: `title: string`, `nodes: array`, `total_credits: number`.
- **canvas_op** - Canvas spatial operation (move/arrange). Key payload fields: `op: string`, `args: object`.

### Data Models
#### AssetObject
Represents a media file produced or used by the agent.

| Field | Type | Description |
| --- | --- | --- |
| `asset_label` | string | Unique label in the session (e.g. `asset_1`) |
| `kind` | string | `"image"` \| `"video"` \| `"audio"` |
| `url` | string | Public CDN URL |
| `source_tool` | string | Tool that created the asset |
| `model` | string \| null | AI model used |
| `prompt` | string \| null | Prompt used |
| `created_at` | string | ISO 8601 timestamp |
```

--------------------------------

### Register uploaded asset request body

Source: https://muapi.ai/docs/design-agent-api

Request body for POST /sessions/{session_id}/assets. Requires a public CDN URL and the media kind. Should be called after uploading to S3 using the signed URL from GET /api/app/get_file_upload_url. The agent can then address the asset by the returned label.

```json
{
  "url": "https://cdn.muapi.ai/uploads/my-photo.jpg",
  "kind": "image",
  "source_tool": "upload",
  "prompt": "User selfie for celebrity collage"
}
```

--------------------------------

### GET /sessions/{session_id}/messages - Response 200 OK

Source: https://muapi.ai/docs/design-agent-api

Success response for fetching full persisted chat history. Contains an array of message objects, each with role, content, optional attachments/events, timestamp, and optionally skill_name. Attachments include asset_label, url, and kind, while assistant events list tool_call and tool_result entries.

--------------------------------

### GET /sessions/{session_id}/jobs - List recent jobs

Source: https://muapi.ai/docs/design-agent-api

Returns the 20 most recent jobs for a session. Useful for detecting and resuming in-flight jobs after a page refresh. Response is a JSON array of job objects.

```json
[
  {
    "id": "job_def456",
    "status": "processing",
    "user_message": "Create an action figure of me",
    "error": null,
    "created_at": "2026-05-08T07:10:00Z",
    "completed_at": null
  }
]
```

--------------------------------

### Create Agent - Response (200 OK)

Source: https://muapi.ai/docs/agents

Example response from the POST /agents endpoint. Returns the created agent object including id, name, description, system_prompt, icon_url, daily_credit_limit, created_at, and skills array.

```json
{
  "id": "agent_12345",
  "name": "Research Assistant",
  "description": "Helps gather information.",
  "system_prompt": "You are a helpful research assistant.",
  "icon_url": null,
  "daily_credit_limit": 100.0,
  "created_at": "2024-01-01T12:00:00Z",
  "skills": [
    {
        "id": "web_search",
        "name": "Web Search",
        ...
    }
  ]
}
```
Tokens:
Raw