Design Agent API

MUAPI Design Agent — API Reference

Design Agent 是一个对话式 AI 系统，可以通过编排 MUAPI 平台上的生成式 AI 模型来生成图片、视频和音频。本文档涵盖 Web 界面使用的全部 API 端点，适合希望以编程方式集成或构建在 Agent 之上的开发者。

Overview（概览）

Base URL: https://api.muapi.ai/api/v1/creative-agent
Auth:     x-api-key: {MUAPIAPP_API_KEY}
Format:   application/json

Architecture（架构）

Agent 使用提交后轮询模式：

  1. 向 /sessions/{id}/chat 发送 POST 消息，或通过 /sessions/{id}/run-skill 触发技能。
  2. 服务器将后台任务加入队列，并立即返回 job_id。
  3. 后台 Worker（SAQ）执行 Agent 回合，包括规划、调用工具和写入事件。
  4. 每 1–2 秒轮询一次 GET /jobs/{job_id}/events?since=<cursor>，直到 done: true。
sequenceDiagram
    participant "Client"
    participant "API"
    participant "Worker"
    participant "Model (MUAPI)"

    "Client"->>"API": POST /sessions/{id}/chat
    "API"-->>"Client": { job_id, status: "pending" }
    "API"->>"Worker": Enqueue task_run_agent_turn

    loop Polling
        "Client"->>"API": GET /jobs/{job_id}/events?since=0
        "API"-->>"Client": { events: [...], done: false }
    end

    "Worker"->>"Model (MUAPI)": generate_image / image_to_video / ...
    "Model (MUAPI)"-->>"Worker": result URL
    "Worker"->>"API": Write tool_result event

    "Client"->>"API": GET /jobs/{job_id}/events?since=N
    "API"-->>"Client": { events: [tool_result], done: true }

Authentication（身份验证）

所有端点都要求在 header 中提供 API Key：

x-api-key: {MUAPIAPP_API_KEY}

Token 可以是：

  • API Key（来自 Muapi Dashboard）
  • 用户 JWT（仅 Muapi Web 客户端使用）

[!IMPORTANT] is_test: true 的 API Key 可以在不计费的情况下完整运行 Agent。

Sessions（会话）

Session 是持久化工作区。每个 Session 保存聊天历史、已生成的资产和 Agent 任务列表。

GET /sessions

列出当前已验证用户的全部 Session，按最近更新时间排序。

Response 200 OK

[
  {
    "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"
  }
]
字段类型说明
idstringSession 唯一标识符
namestring便于阅读的 Session 名称
credits_spentnumber本 Session 消耗的总 credits
asset_countnumber生成或上传的资产总数
created_atISO 8601Session 创建时间
updated_atISO 8601最近活动时间

POST /sessions

创建新的 Session。

Request Body（可选）

{
  "name": "Product Campaign"
}

省略 name 时，会生成类似 session-a1b2c3 的随机名称。

Response 200 OK

{
  "id": "sess_xyz789",
  "name": "Product Campaign",
  "credits_spent": 0,
  "asset_count": 0
}

PATCH /sessions/{session_id}

重命名已有 Session。

Path Parameters

参数类型说明
session_idstring要重命名的 Session ID

Request Body

{
  "name": "Summer Collection Ads"
}

Response 200 OK

{
  "id": "sess_xyz789",
  "name": "Summer Collection Ads"
}

DELETE /sessions/{session_id}

永久删除 Session 以及与其关联的所有资产、消息和任务。

Response 200 OK

{
  "status": "deleted"
}

Assets（资产）

Asset 是附加到 Session 的任意媒体文件（图片、视频或音频），可以由用户上传，也可以由 Agent 生成。

GET /sessions/{session_id}/assets

获取 Session 注册的全部资产，按创建时间排序（最早的在前）。

Response 200 OK

[
  {
    "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"
  }
]
字段类型说明
asset_labelstringAgent 可寻址的标签（例如 asset_1），在聊天中用于引用特定资产。
kindstringimage、video 或 audio
urlstring媒体文件的 CDN URL
source_toolstring资产的创建方式，例如 upload、generate_image、edit_image、image_to_video 等
modelstring 或 null生成资产所用的模型
promptstring 或 null生成时使用的提示词
created_atISO 8601资产注册时间

POST /sessions/{session_id}/assets

注册上传到外部的资产，使 Agent 可以在后续回合中通过标签（例如 asset_3）引用它。

[!TIP] 应先使用 GET /api/app/get_file_upload_url 返回的 signed URL 将文件直接上传到 S3，再调用此端点。参见下方的 File Upload 部分。

Request Body

{
  "url": "https://cdn.muapi.ai/uploads/my-photo.jpg",
  "kind": "image",
  "source_tool": "upload",
  "prompt": "User selfie for celebrity collage"
}
字段类型必填说明
urlstring✅已上传文件的公开 CDN URL
kindstring✅image、video 或 audio
source_toolstring❌默认为 upload
promptstring❌可选的描述或说明

Response 200 OK

{
  "asset_label": "asset_3",
  "kind": "image",
  "url": "https://cdn.muapi.ai/uploads/my-photo.jpg",
  "source_tool": "upload"
}

[!NOTE] asset_label 会在每个 Session 内以原子方式递增（例如 asset_1、asset_2 等）。在聊天中引用资产时，应始终使用响应返回的标签。

Chat Messages（聊天消息）

GET /sessions/{session_id}/messages

获取 Session 中完整持久化的聊天历史。

Response 200 OK

[
  {
    "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"
  }
]

PATCH /sessions/{session_id}/messages

持久化或覆盖 Session 的完整聊天历史。每次回合完成后，前端会自动调用此端点以确保数据持久性。

Request Body

{
  "messages": [
    { "role": "user", "content": "...", "timestamp": "..." },
    { "role": "assistant", "content": "...", "events": [...], "timestamp": "..." }
  ]
}

Response 200 OK

{
  "status": "saved",
  "count": 4
}

Agent Execution（Agent 执行）

POST /sessions/{session_id}/chat

向 Agent 发送自由格式消息。Agent 会分析意图、规划工具调用并执行（例如生成图片、视频和音频）。这是对话交互的主要入口。

Request Body

{
  "message": "Create a selfie of me with Harry Potter on set",
  "model": "gpt-5-mini",
  "messages_snapshot": [...],
  "canvas_state": {
    "viewport": { "x": 0, "y": 0, "scale": 1 },
    "selected": "asset_2",
    "nodes": [
      { "asset_id": "asset_1", "kind": "image", "x": 100, "y": 200, "w": 400, "h": 400 },
      { "asset_id": "asset_2", "kind": "image", "x": 600, "y": 200, "w": 400, "h": 400 }
    ]
  }
}
字段类型必填说明
messagestring✅用户发送给 Agent 的消息
modelstring❌使用的规划 LLM。默认为 gpt-5-mini。
messages_snapshotarray❌此回合之前的完整聊天历史，用于提供上下文，并以原子方式持久化。
canvas_stateobject❌用户画布布局快照，用于空间推理，例如“使用左侧的资产”。

Response 200 OK

{
  "job_id": "job_def456",
  "status": "pending"
}

[!IMPORTANT] 此端点会立即返回。Agent 在后台异步运行；请轮询 GET /jobs/{job_id}/events 跟踪进度。

POST /sessions/{session_id}/run-skill

直接调用指定名称的专家技能，跳过 Agent 的意图识别步骤。指定技能的配方会被渲染成结构化提示词并发送给 Agent。

Request Body

{
  "skill_name": "fashion-try-on",
  "inputs": {
    "person_image": "asset_1",
    "clothing_image": "asset_2"
  },
  "model": "gpt-5-mini",
  "messages_snapshot": [...]
}
字段类型必填说明
skill_namestring✅技能的精确 slug 名称（参见 GET /agent-skills）
inputsobject❌技能输入变量的键值映射
modelstring❌规划 LLM，默认为 gpt-5-mini。
messages_snapshotarray❌用于持久化的聊天历史快照

Response 200 OK

{
  "job_id": "job_ghi789",
  "status": "pending"
}

GET /agent-skills

列出从 agent/skills/*.skill.md 加载的所有可用专家技能配方。

Response 200 OK

[
  {
    "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...",
    ...
  }
]

Available Skills（截至 2026 年 5 月）

技能名称说明主要模型
selfie-with-celebrities将自拍与电影演员合成nano-banana-2-edit、kling-o1-image-to-video
animal-video-generator有趣的拟人动物 Vloggernano-banana、veo3.1-fast-image-to-video
ugc-ads-workflowInfluencer 风格的产品 UGC 广告gpt-image-2、seedance-v1.5-pro-i2v-fast
cartoon-dance-animationPixar 风格的 3D 角色舞蹈nano-banana-2-edit、kling-v2.6-std-motion-control
character-story-video根据图片生成多段故事视频nano-banana-2-edit
action-figure-generator包装中的 3D 收藏级动作人偶nano-banana-2-edit
fashion-try-on虚拟试衣 + 模特视频qwen-image-edit-2511、seedance-v1.5-pro-i2v-fast
floor-plan-rendering2D 平面图 → 3D 建筑渲染nano-banana-2、nano-banana-2-edit
interior-design-visualizer空房间 → 带家具的室内空间gpt-image-2、nano-banana-2-edit
multi-angle-reshoot6 种戏剧化摄像机角度变化nano-banana-2-edit
couple-grid-creator6 格浪漫情侣姿势网格qwen-image-edit-plus
giant-product-showcase人物与建筑大小的产品同框nano-banana-2-edit、veo3.1-fast-image-to-video
product-showcase-video爆炸式食材产品广告bytedance-seedream-v5.0-edit、seedance-v1.5-pro-i2v-fast
jewelry-product-video奢华微距珠宝商业广告nano-banana-2-edit、grok-imagine-image-to-video
3d-logo-animation2D Logo → 3D 动画展示nano-banana-2-edit、veo3.1-fast-image-to-video
talking-baby-video穿着服装的病毒式会说话婴儿nano-banana、grok-imagine-image-to-video
keyboard-art-maker用键帽拼出自定义消息ideogram-v3-t2i
product-video-ad-maker电影感产品视频广告flux-2-pro-edit、wan2.5-image-to-video-fast

Job Management（任务管理）

Job 代表一次 Agent 回合（一次消息 → 一次响应周期）。

GET /jobs/{job_id}/events

轮询 Agent 在一次任务回合中产生的流式事件。使用基于 cursor 的分页，只接收上次轮询之后的新事件。

Query Parameters

参数类型默认值说明
sinceinteger0只返回 id > since 的事件。新的轮询从 0 开始。
limitinteger200每次调用最多返回的事件数（最大 1000）。

Response 200 OK

{
  "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
}
字段类型说明
statusstring当前状态：pending、processing、completed、failed
approvedboolean 或 null已批准时为 true、拒绝时为 false、等待时为 null
approval_requestedbooleanAgent 当前等待用户确认时为 true
cursornumber下一次轮询使用的 cursor
eventsobject[]自上次轮询以来的事件列表
errorstring错误信息（status 为 failed 时提供）
doneboolean任务完成时为 true

Event Types Reference（事件类型参考）

type说明主要 Payload 字段
text流式 Agent 文本（聊天气泡内容）content: string
info状态消息（例如“Waiting for approval...”）content: string、needs_approval: boolean
error发生错误message: string
tool_callAgent 即将调用工具name: string、args: object
tool_result工具调用完成，包含新资产name: string、result: object、asset: AssetObject
plan_proposeAgent 提出等待批准的生成计划title: string、nodes: array、total_credits: number
canvas_op画布空间操作（移动/排列）op: string、args: object

Data Models（数据模型）

AssetObject

表示 Agent 生成或使用的媒体文件。

字段类型说明
asset_labelstringSession 内的唯一标签（例如 asset_1）
kindstringimage、video 或 audio
urlstring公开 CDN URL
source_toolstring创建资产的工具
modelstring 或 null使用的 AI 模型
promptstring 或 null使用的提示词
created_atstringISO 8601 时间戳

GET /sessions/{session_id}/jobs

列出某个 Session 最近的 20 个任务。页面刷新后，可用它检测并恢复正在执行的任务。

Response 200 OK

[
  {
    "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
  }
]

POST /jobs/{job_id}/approve

批准已提出的计划。Agent 会在执行工具调用前等待批准。轮询 /jobs/{job_id}/events，确认 Agent 已恢复运行。

Response 200 OK

{
  "status": "approved"
}

POST /jobs/{job_id}/reject

拒绝已提出的计划。Agent 会停止执行并报告拒绝结果。

Response 200 OK

{
  "status": "rejected"
}

POST /jobs/{job_id}/cancel

取消正在执行的任务。Worker 会在工具调用之间检查此标记，并停止派发新的调用。已经在执行中的模型请求仍可能完成。

Response 200 OK

{
  "status": "cancelled"
}

File Upload（文件上传）

Design Agent 使用直传 S3 的上传方式，避免将二进制数据经过 API 服务器传输。

Step 1 — Get a Signed Upload URL（获取签名上传 URL）

GET /api/app/get_file_upload_url（Dashboard API，使用独立前缀）

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

Response

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

Step 2 — Upload Directly to S3（直接上传到 S3）

POST <url from above>
Content-Type: multipart/form-data

[all fields from response, then the file itself]

最终 CDN URL 为：https://cdn.muapi.ai/<fields.key>

Step 3 — Register with Session（向 Session 注册）

POST /api/v1/creative-agent/sessions/{session_id}/assets
{
  "url": "https://cdn.muapi.ai/uploads/user_123/abc/my-photo.jpg",
  "kind": "image",
  "source_tool": "upload"
}

响应会返回 asset_label（例如 "asset_3"），之后的消息可以使用它来引用资产。

Complete Workflow Example（完整工作流示例）

下面是使用 JavaScript（fetch）完成端到端流程的示例：

const API = "https://api.muapi.ai/api/v1/creative-agent";
const headers = {
  "Content-Type": "application/json",
  "x-api-key": "YOUR_API_KEY",
};

// 1. Create a session
const session = await fetch(`${API}/sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "My Campaign" }),
}).then((r) => r.json());
// => { id: "sess_abc", name: "My Campaign", ... }

// 2. (Optional) Upload a reference image
const uploadRes = await fetch(
  `/api/app/get_file_upload_url?filename=product.jpg`,
  { headers },
).then((r) => r.json());
// ... upload file to S3 using uploadRes.url and uploadRes.fields ...
const assetRes = await fetch(`${API}/sessions/${session.id}/assets`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: `https://cdn.muapi.ai/${uploadRes.fields.key}`,
    kind: "image",
  }),
}).then((r) => r.json());
// => { asset_label: "asset_1", ... }

// 3. Send a message (referencing the uploaded asset)
const job = await fetch(`${API}/sessions/${session.id}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: `Create a viral product showcase video using asset_1`,
    model: "gpt-5-mini",
  }),
}).then((r) => r.json());
// => { job_id: "job_xyz", status: "pending" }

// 4. Poll for events
let cursor = 0;
let done = false;
while (!done) {
  await new Promise((r) => setTimeout(r, 1500));
  const poll = await fetch(`${API}/jobs/${job.job_id}/events?since=${cursor}`, {
    headers,
  }).then((r) => r.json());

  for (const ev of poll.events) {
    if (ev.type === "plan_propose") {
      // Approve the plan automatically (or show user for confirmation)
      await fetch(`${API}/jobs/${job.job_id}/approve`, {
        method: "POST",
        headers,
      });
    }
    if (ev.type === "tool_result" && ev.payload.asset) {
      console.log("Generated asset:", ev.payload.asset.url);
    }
    if (ev.type === "text") {
      process.stdout.write(ev.payload.content);
    }
  }

  cursor = poll.cursor;
  done = poll.done;
}

// 5. Fetch final asset list
const assets = await fetch(`${API}/sessions/${session.id}/assets`, {
  headers,
}).then((r) => r.json());
console.log("All session assets:", assets);

Error Handling（错误处理）

所有错误都会返回标准 HTTP 状态码和 JSON body：

{
  "detail": "Session not found"
}
状态码含义
400Bad request / validation error（请求错误或验证错误）
401Missing or invalid auth token（缺少或无效的身份验证 token）
403Forbidden（访问其他用户的资源）
404找不到 Session、Job、Asset 或 Skill
422字段值无效，例如不支持的 kind
500内部服务器错误

[!WARNING] 如果轮询响应中 done: true 且 status: "failed"，请检查 error 字段，其中包含经过清理的模型提供商错误信息。

Rate Limits & Credits（速率限制与 Credits）

  • 每次工具调用都会从账户余额消耗 credits。
  • plan_propose 事件会在执行前显示 total_credits 估算值。
  • 使用 POST /jobs/{job_id}/reject 可以在不花费 credits 的情况下取消计划。
  • Sandbox API Key（is_test: true）不会消耗 credits。
MUAPI Design Agent — API Reference — Muapi Docs