LangChain 集成

官方 muapi-langchain 包将 MuAPI 的 390 多种生成式媒体模型、40 多个命名 Skill 和创意 Agent 封装为符合 LangChain 使用习惯的原语。你可以将它们放入 ReAct Agent、LangGraph 节点或 Deep Agent 中，让 LLM 能够创建图像、视频、音频、编辑结果以及完整的多素材营销活动。

包	用途
muapi-langchain	LangChain 工具 + 文档加载器 + 成本回调 + Deep Agents 示例

安装

目前该集成以源码形式发布在 muapi-cli 仓库中（PyPI 版本即将推出）：

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

# 可选：用于下面的 Deep Agents 配方
pip install "deepagents langgraph langchain-openai"

设置 API key（或使用 muapi auth configure）：

export MUAPI_API_KEY="..."

包含内容

该集成提供四个工具，形成从低成本发现到开放式创意规划的能力梯度：

工具	功能	成本
`muapi_select`	根据创意简报为模型和命名 Skill 排名	免费
`muapi_generate`	单次生成（图像 / 视频 / 音频 / 编辑 / 增强）	按次计费
`muapi_run_skill`	运行命名的多步骤配方（UGC 广告、故事板、产品视频等）	按配方计费
`muapi_creative_agent`	将多素材简报交给 MuAPI 规划 Agent	取决于任务

另外还有两个非工具原语：

MuapiAssetLoader — 将之前的生成结果加载为 LangChain Document，用于 RAG
MuapiCostCallback — 追踪一次运行中的积分消耗，并强制执行硬性预算上限

快速开始

from muapi_langchain import muapi_select, muapi_generate
import json

# 发现候选模型（免费 — 不消耗积分）
result = muapi_select.invoke({
    "intent": "cinematic product photo of a sneaker",
    "kind": "image",
    "tier": "best",
    "limit": 3,
})
print(json.loads(result)["models"])

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

这些工具只是普通的 @tool 装饰函数，因此可以在任何 LangChain Agent 框架中工作 — create_react_agent、自定义 LangGraph 图、Deep Agents，或通过 OpenAI / Anthropic SDK 直接调用工具。

工具参考

`muapi_select(intent, kind?, tier?, limit=5)`

根据用户意图为候选模型和 Skill 排名。该工具免费 — 它在本地使用关键字重叠排序器，对内置的 390 模型目录进行匹配。

intent：用户需求的自然语言描述。
kind：可选 — "image"、"image_edit"、"video"、"i2v"、"video_edit"、"lipsync"、"audio"、"enhance"、"3d" 之一。
tier：可选 — "best"、"balanced"、"fast" 或 "budget"。

当你不知道应该选择哪个模型，或想找出与简报匹配的命名 Skill 时，先使用这个工具。

`muapi_generate(prompt, kind="image", model="auto", input_asset_url?, tier="balanced", extra?)`

生成一个素材。使用 model="auto" 时，MuAPI 会根据 kind 和 tier 选择合适的默认模型。对于编辑、图像转视频、口型同步和增强任务，请传入 input_asset_url。

muapi_generate.invoke({
    "prompt": "make the cat wear a top hat",
    "kind": "image_edit",
    "input_asset_url": "https://...source.png",
})

`muapi_run_skill(skill_name, inputs)`

运行 40 多个预置的多步骤配方之一（ugc-ads-workflow、storyboard、product-ad-cinematic、3d-logo-animation 等）。通过 muapi_select 发现 Skill 名称及其输入 Schema。

`muapi_creative_agent(brief, budget_credits=300)`

将自由格式的多素材简报交给 MuAPI 规划 Agent。Agent 会将简报拆解为 DAG，执行并返回素材。该工具可能消耗大量积分，生产环境应通过 interrupt_on 进行审批控制。

文档加载器

MuapiAssetLoader 会将之前的生成结果加载为 LangChain Document：page_content 是原始提示词，metadata 包含素材 URL、模型、类型和积分成本。它适用于 RAG（“用相同风格再做一个”）以及对用户生成历史进行评估。

from muapi_langchain import MuapiAssetLoader

docs = MuapiAssetLoader(request_ids=["req_abc", "req_def"]).load()
for d in docs:
    print(d.metadata["url"], "·", d.page_content[:80])

成本追踪

MuapiCostCallback 可以接入任何 LangChain / LangGraph 运行。它会检查每个 MuAPI 工具结果、累计积分、为每次调用触发自定义事件，并可在达到上限时抛出 BudgetExceeded，在 Agent 失控消耗前干净地中止运行。

from muapi_langchain import MuapiCostCallback

cost_cb = MuapiCostCallback(
    budget_credits=500,
    on_event=lambda evt, payload: print(evt, payload),
)

agent.invoke(
    {"messages": [{"role": "user", "content": "make me a 3-shot carousel ..."}]},
    config={"callbacks": [cost_cb]},
)

print(cost_cb.summary())
# {'total_credits': 78, 'calls': 4, 'by_tool': {'muapi_generate': 78}, ...}

Deep Agents 配方

推荐的生产模式将工具分配给一个规划器（低成本发现 + 单素材生成）和一个 creative-specialist 子 Agent（多步骤 Skill + 创意 Agent）。开放式创意工作通过 interrupt_on 交由人工审批。

import os, uuid
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command
from muapi_langchain import (
    MuapiCostCallback, PLANNER_TOOLS, SPECIALIST_TOOLS,
)

CREATIVE_SPECIALIST = {
    "name": "creative-specialist",
    "description": (
        "Handles multi-step MuAPI workflows: named skills (UGC ads, "
        "storyboards, product videos) and open-ended creative briefs."
    ),
    "system_prompt": (
        "You are a MuAPI creative specialist. "
        "Prefer muapi_run_skill when the brief matches a named recipe. "
        "Escalate to muapi_creative_agent only for open-ended multi-asset briefs."
    ),
    "tools": SPECIALIST_TOOLS,
}

agent = create_deep_agent(
    model=ChatOpenAI(model="gpt-4o", api_key=os.environ["OPENAI_API_KEY"]),
    tools=PLANNER_TOOLS,
    subagents=[CREATIVE_SPECIALIST],
    system_prompt=(
        "Start with muapi_select to discover models and skills. "
        "Call muapi_generate yourself for single-asset asks. "
        "Delegate multi-step work to the creative-specialist."
    ),
    interrupt_on={
        "muapi_creative_agent": {"allowed_decisions": ["approve", "edit", "reject"]},
    },
    checkpointer=MemorySaver(),
)

cost_cb = MuapiCostCallback(budget_credits=500)
config = {"configurable": {"thread_id": str(uuid.uuid4())}, "callbacks": [cost_cb]}

result = agent.invoke(
    {"messages": [{"role": "user", "content":
        "Make a 3-shot Instagram carousel for SunFizz mango sparkling water."
    }]},
    config=config,
    version="v2",
)

# Resume after each interrupt
while getattr(result, "interrupts", None):
    action = result.interrupts[0].value["action_requests"][0]
    print(f"Pending: {action['name']}")
    print(f"Args:    {action['args']}")
    decision = input("approve / edit / reject: ").strip().lower()
    result = agent.invoke(
        Command(resume={"decisions": [{"type": decision}]}),
        config=config,
        version="v2",
    )

print(cost_cb.summary())

完整可运行版本位于 integrations/langchain/examples/deep_agents_demo.py。

决策树

用户简报
  ├─ 不知道该用哪个模型/Skill？  → muapi_select          （免费，规划器）
  ├─ 单个素材且提示词明确？      → muapi_generate        （规划器）
  ├─ 匹配已知配方？              → muapi_run_skill       （专家）
  └─ 多素材 / 多模态？           → muapi_creative_agent  （专家，需审批）

环境变量

变量	必填	说明
`MUAPI_API_KEY`	是	MuAPI key，也可以通过 `muapi auth configure` 设置
`OPENAI_API_KEY`	使用 Deep Agents 时需要	为示例中的规划器 LLM 提供能力
`MUAPI_BASE_URL`	否	默认值为 `https://api.muapi.ai/api/v1`

开发时可以创建一个沙盒 Key（is_test=true），它会立即返回模拟 URL，且永远不会扣除积分 — 创建方式请参阅 CLI 文档。