Magic Genie for Agents
One command to setup. Then search, run, done.
Setup Your Agent
Preview: real one-time URL is generated when you copy.
npm install nbardy/magic-genie-client
npx magic-genie setup "https://magicgenie.ai/agent_auth/{user_id}/one-time-password-***"Checking session...
Try it out
After running the setup command, your agent has the magic-genie CLI and auto-loads credentials from .magic_genie_env.
# Search for the right workflow magic-genie search "hoodie mockup" # Run a spell with a local image (auto base64 encoded) magic-genie run merch-seller merch-drop-hoodie \ --type wish --image-file ./logo.png \ --prompt "Easter collection" --download output.jpg # Run with a video (auto signed-URL upload) magic-genie run video-editor highlight-reel \ --type spell --video-file ./raw.mp4 \ --prompt "15-second cut"
Why Workflows?
Stop Juggling Models. Start Finishing Tasks.
Use one stable integration instead of re-picking models, prompts, and file handling for every creative job. Your agent can stay focused on selecting the right workflow and passing user context, while Magic Genie handles the operator stack behind the API.
See Agent Pricingdiscovery
execution
recovery
🧠 Why Agents Need Magic Genie
Agents are strong at reasoning, but multimedia jobs break down when they have to infer model choice, prompt structure, and file handling on every request. Magic Genie narrows that surface to a smaller contract: search for a workflow, pass a local file or URL, and get back result URLs. The client handles auth, base64 encoding for images, and signed-URL uploads for videos automatically.
✕ Without a Workflow Layer
- Every job requires fresh prompt and model selection logic.
- File upload, routing, and retry behavior have to be reinvented per tool.
- Credit exhaustion becomes a custom recovery path instead of a standard one.
- Catalog discovery is implicit and expensive for the agent to reason about.
✓ With Magic Genie
- Public Catalog: Discover live persona and capability entries from one endpoint.
- One Client:
npm install nbardy/magic-genie-client— handles auth, file encoding, and uploads. - Clear Billing: Credit costs are exposed in catalog entries and 402 responses.
- Production Outputs: Return asset URLs instead of intermediate model chatter.
🛡️ Built for Agent Psychology
The goal is to reduce brittle orchestration work inside the agent loop, not add another giant integration surface.
Compact Discovery
The public catalog exposes the persona, capability, credit cost, and input/output contracts your agent needs to decide quickly.
Lower Retry Friction
Input contracts are explicit, and credit failures return machine-readable purchase actions instead of leaving the agent to invent a recovery flow.
Stable Route Surface
Your agent does not need a different integration per capability. Discovery lives at `/v1/catalog` and execution lives at `/v1/run`.
Credit-Aware Execution
Visibility, pack pricing, and retry behavior are explicit, so the agent can make cost-aware choices instead of guessing.
How It Fits Into Your Agent Stack
1. Discover the Job Surface
Pull the live catalog, filter by persona or capability, and inspect the published credit cost and JSON contract before the agent chooses a workflow.
That turns vague multimedia requests into a narrower planning problem: select the right capability, then fill a known contract.
2. Execute With One Route
Send `personaSlug`, `capabilitySlug`, and `inputs` to `/v1/run`. The public run contract stays stable even as the internal operator stack changes.
That keeps your agent code small. It only needs to map the user request to the correct catalog entry and supply the source asset plus prompt context.
3. Recover, Fund, Retry
If credits run out, the API returns HTTP 402 with purchase actions for saved-card top-ups, Stripe Checkout, and optional x402 flows when configured.
Agents can treat billing as another structured branch: inspect the response, fund the account, and retry the original execution without custom scraping.
🤖 Example Integration
A minimal agent integration only needs catalog discovery, one execution route, and a 402 retry branch.
import { MagicGenieClient } from "magic-genie-client";
// Reads .magic_genie_env automatically
const client = await MagicGenieClient.create();
// 1. Search for the right workflow
const workflows = await client.search("meme", {
persona: "influencer",
});
// 2. Run it — local files are handled automatically
// Images < 10MB: base64 inline
// Images > 10MB: signed URL upload
// Videos: always signed URL upload
const result = await client.run({
personaSlug: "influencer",
capabilitySlug: "memeify",
capabilityType: "spell",
imageFile: "./source.jpg", // local file, auto encoded
prompt: "Keep it reaction-meme ready",
});
console.log(result.outputUrl);
// 3. Download the result
await client.download(result.outputUrl, "meme.jpg");Or use the CLI directly from your agent's shell:
# Install npm install nbardy/magic-genie-client # Search, run, done magic-genie search "hoodie" magic-genie run merch-seller merch-drop-hoodie \ --type wish --image-file ./logo.png \ --prompt "Easter collection" --download output.jpg
💳 Ways to Pay
These are the payment paths implemented in the repo today:
Saved-Card Top-Up
`POST /api/billing/buy-credits` charges a saved Stripe payment method and grants credits immediately.
Stripe Checkout Setup
`POST /api/billing/checkout` starts a browser-based setup flow for first-time card capture or subscription checkout.
x402 Protocol
`POST /api/x402/cast` is available when x402 is configured, giving agents a payment-required recovery path over Base.
One-Time Key Setup
Generate a short-lived setup link, download `.magic_genie_env`, then use the resulting `mg_*` key as Bearer auth for agent-owned runs.
📋 All Available Personas
When your agent queries our catalog, it can access specialized tools tailored for these exact roles and jobs to be done: