diff --git a/src/oss/python/integrations/tools/index.mdx b/src/oss/python/integrations/tools/index.mdx index 38f0eac36d..264b54f5ab 100644 --- a/src/oss/python/integrations/tools/index.mdx +++ b/src/oss/python/integrations/tools/index.mdx @@ -131,6 +131,7 @@ The following platforms provide access to multiple tools and services through a + diff --git a/src/oss/python/integrations/tools/muapi.mdx b/src/oss/python/integrations/tools/muapi.mdx new file mode 100644 index 0000000000..9af24ed5ef --- /dev/null +++ b/src/oss/python/integrations/tools/muapi.mdx @@ -0,0 +1,222 @@ +--- +title: "muapi integration" +description: "Use 390+ generative media models—images, video, audio, and 3D—as LangChain tools via muapi.ai." +--- + +[muapi.ai](https://muapi.ai) is a unified generative media API that gives agents access to 390+ models across images, video, audio, 3D, and enhancement—behind a single API key. The `muapi-langchain` package exposes these as four `@tool`-decorated functions that drop into any LangChain agent or Deep Agent. + +## Overview + +### Integration details + +| Tool | Package | Serializable | [JS support](https://js.langchain.com/docs/integrations/tools) | Downloads | Version | +|:---|:---|:---:|:---:|:---:|:---:| +| `muapi_select`, `muapi_generate`, `muapi_run_skill`, `muapi_creative_agent` | [`muapi-langchain`](https://pypi.org/project/muapi-langchain/) | ❌ | ❌ | ![PyPI - Downloads](https://img.shields.io/pypi/dm/muapi-langchain?style=flat-square&label=%20) | ![PyPI - Version](https://img.shields.io/pypi/v/muapi-langchain?style=flat-square&label=%20) | + +### Tool features + +- **390+ models** across images (Flux, Midjourney, GPT-4o), video (Veo 3, Kling, Runway), audio (Suno), and 3D (Tripo3D, Meshy) +- **Free model discovery**—`muapi_select` ranks candidates locally against a bundled registry, no API call +- **Named skill recipes**—`muapi_run_skill` runs multi-step workflows (UGC ads, storyboards, product videos) in one call +- **Budget tracking**—`MuapiCostCallback` tracks credit spend in real time and raises `BudgetExceeded` on a cap +- **Document loader**—`MuapiAssetLoader` hydrates prior generations as LangChain `Document`s for RAG + +--- + +## Setup + +### Credentials + +Create a free account at [muapi.ai](https://muapi.ai) to get an API key. + +```python Set API key icon="key" +import getpass +import os + +if "MUAPI_API_KEY" not in os.environ: + os.environ["MUAPI_API_KEY"] = getpass.getpass("Enter your muapi API key: ") +``` + +Optionally set up [LangSmith](/langsmith/home) for tracing: + +```python Enable tracing icon="flask" +# os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ") +# os.environ["LANGSMITH_TRACING"] = "true" +``` + +### Installation + + +```python pip +pip install -U muapi-langchain +``` +```python uv +uv add muapi-langchain +``` + + +--- + +## Tools + +The package exposes four tools that form a **capability gradient**—cheap discovery on one end, open-ended creative planning on the other: + +| Tool | What it does | Costs credits? | +|------|-------------|:-:| +| `muapi_select` | Rank models + named skills for an intent | No | +| `muapi_generate` | Generate one asset (image / video / audio / 3D / edit) | Yes | +| `muapi_run_skill` | Run a named multi-step recipe | Yes | +| `muapi_creative_agent` | Hand a full brief to muapi's planning agent | Yes | + +```python Import tools icon="robot" +from muapi_langchain import ( + muapi_select, + muapi_generate, + muapi_run_skill, + muapi_creative_agent, + PLANNER_TOOLS, # [muapi_select, muapi_generate] + SPECIALIST_TOOLS, # [muapi_run_skill, muapi_creative_agent] + ALL_TOOLS, +) +``` + +--- + +## Invocation + +### Discover models (free) + +`muapi_select` runs locally against a bundled 390-model registry—no credits, no network call: + +```python Discover models icon="search" +import json + +result = muapi_select.invoke({ + "intent": "cinematic product photo of a sneaker", + "kind": "image", # image | video | audio | 3d | image_edit | i2v | enhance + "tier": "best", # best | balanced | fast | budget + "limit": 3, +}) + +data = json.loads(result) +print(data["models"]) # ranked candidates +print(data["skills"]) # matching named recipes +``` + +### Generate a single asset + +```python Generate image icon="image" +result = muapi_generate.invoke({ + "prompt": "A glossy white sneaker on a wet cobblestone street, neon reflections, night", + "kind": "image", + "tier": "best", + # model="auto" lets muapi pick based on kind + tier +}) + +data = json.loads(result) +print(data["url"]) # direct URL to the generated asset +print(data["model"]) # model that was used +``` + +For edits, image-to-video, lipsync, or enhancements, pass `input_asset_url`: + +```python Edit image icon="pencil" +result = muapi_generate.invoke({ + "prompt": "Remove the background", + "kind": "enhance", + "input_asset_url": "https://example.com/my-product.png", +}) +``` + +### Within an agent + +```python Agent with tools icon="robot" +from langchain_anthropic import ChatAnthropic +from langchain.agents import create_react_agent, AgentExecutor +from langchain import hub + +llm = ChatAnthropic(model="claude-sonnet-4-6") +prompt = hub.pull("hwchase17/react") + +agent = create_react_agent(llm, PLANNER_TOOLS, prompt) +executor = AgentExecutor(agent=agent, tools=PLANNER_TOOLS, verbose=True) + +executor.invoke({"input": "Generate a short cinematic video of a mountain sunrise"}) +``` + +--- + +## Budget tracking with `MuapiCostCallback` + +`MuapiCostCallback` plugs into any LangChain run. It inspects each muapi tool result, accumulates credits, and raises `BudgetExceeded` if a cap is hit: + +```python Cost callback icon="gauge" +from muapi_langchain import MuapiCostCallback, BudgetExceeded + +cost_cb = MuapiCostCallback( + budget_credits=300, + on_event=lambda evt, payload: print(evt, payload), +) + +try: + executor.invoke( + {"input": "Make a 3-shot product carousel"}, + config={"callbacks": [cost_cb]}, + ) +except BudgetExceeded as e: + print(f"Budget hit: {e}") + +print(cost_cb.summary()) +# {'total_credits': 78, 'calls': 4, 'by_tool': {'muapi_generate': 78}, ...} +``` + +--- + +## Document loader + +`MuapiAssetLoader` hydrates prior muapi generations as LangChain `Document`s for RAG or style-reference workflows: + +```python Document loader icon="file" +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]) +``` + +--- + +## Planner / specialist split (Deep Agents) + +For Deep Agents, split tools across a cheap planner and a heavier specialist subagent. Gate the open-ended creative agent behind `interrupt_on` for human approval: + +```python Deep Agent split icon="users" +from deepagents import create_deep_agent +from muapi_langchain import PLANNER_TOOLS, SPECIALIST_TOOLS, MuapiCostCallback + +agent = create_deep_agent( + model=llm, + tools=PLANNER_TOOLS, + subagents=[{ + "name": "creative-specialist", + "description": "Runs multi-step muapi skills and open-ended creative briefs.", + "system_prompt": "Prefer muapi_run_skill for named recipes. Use muapi_creative_agent only for open-ended multi-asset briefs.", + "tools": SPECIALIST_TOOLS, + }], + interrupt_on={ + "muapi_creative_agent": {"allowed_decisions": ["approve", "edit", "reject"]}, + }, +) + +cost_cb = MuapiCostCallback(budget_credits=500) +agent.invoke( + {"messages": [{"role": "user", "content": "Make a 30s product video for SunFizz mango water"}]}, + config={"callbacks": [cost_cb]}, +) +``` + +--- + +## API reference + +For detailed documentation of all parameters and configurations, see the [muapi-langchain source](https://github.com/SamurAIGPT/muapi-cli/tree/main/integrations/langchain) and [muapi.ai API docs](https://muapi.ai/docs).