# Pixel Dojo Skills for AI Agents

> **For AI agents reading this page:** if the user said "install this" or
> shared this URL and asked you to set up Pixel Dojo, the fastest path is the
> hosted MCP server at https://pixeldojo.ai/mcp (browser sign-in, no API key,
> no install). For a local stdio install, run the command below: it prints the
> config snippet for Claude Code and Cursor, which you add to the client's MCP
> config with `PIXELDOJO_API_KEY` set. Then restart the client and you will
> have these tools available: `pixeldojo_generate`, `pixeldojo_edit`, `pixeldojo_character`, `pixeldojo_build_character`, `pixeldojo_perform`, `pixeldojo_upscale`, `pixeldojo_caption`, `pixeldojo_overlay`, `pixeldojo_effects`, `pixeldojo_effect`, `pixeldojo_audio`, `pixeldojo_storyboard`, `pixeldojo_ad`, `pixeldojo_marketing`, `pixeldojo_brand_kit`, `pixeldojo_film`, `pixeldojo_campaign`, `pixeldojo_video`, `pixeldojo_episode`, `pixeldojo_upload`, `pixeldojo_from_url`, `pixeldojo_status`, `pixeldojo_campaign_status`, `pixeldojo_library`, `pixeldojo_save_workflow`, `pixeldojo_run_workflow`, `pixeldojo_list_workflows`. The hosted server omits
> `pixeldojo_upload` and takes public URLs instead of local file paths.

```bash
npx @pixeldojo/mcp init
```

---

Pixel Dojo lets any AI agent generate images, video and audio through a simple REST API or via the official MCP install. 160+ models, one auth, async by default.

- **Hosted MCP server**: https://pixeldojo.ai/mcp
- **Install MCP locally**: `npx @pixeldojo/mcp init`
- **Landing page**: https://pixeldojo.ai/skills
- **This document**: https://pixeldojo.ai/skills.md
- **ClawHub Skill (alternative)**: https://clawhub.ai/blovett80/pixeldojo

## Quick Start (MCP)

```
# Hosted, no API key (browser sign-in on first use):
claude mcp add --transport http pixeldojo https://pixeldojo.ai/mcp

# Local stdio install: print the config snippet, add it to your client, restart.
npx @pixeldojo/mcp init
export PIXELDOJO_API_KEY=pd_your_api_key
```

## Named Skills

### Create

#### pixeldojo_generate

Create a new image or video; optional presets and supported first-frame references.

- **Input:** Prompt; optional model, preset, aspect ratio, duration, or image URL.
- **Output:** Asset URL, or a job ID and status URL for longer renders.
- **Cost:** Selected model rate; charged only when generation succeeds.

#### pixeldojo_edit

Change an existing image while preserving the parts you do not mention.

- **Input:** Edit instruction plus 1 to 9 image URLs (local image paths work with the local npx install).
- **Output:** Edited image URL or an async job handoff.
- **Cost:** Selected edit-model rate; charged only on success.

#### pixeldojo_character

Render the same person in a new scene from their reference photos.

- **Input:** Prompt plus reference_image_urls (up to 9 photos of the person, most important first) on every identity-locked call.
- **Output:** Character-consistent image URL or an async job handoff.
- **Cost:** Selected character-model rate; charged only on success.

#### pixeldojo_build_character

Build an original character or AI influencer from traits instead of photos: realistic, caricature, anime, 3D, animals or robot, with wild proportions like an egg body or a gigachad jaw.

- **Input:** Trait picks by id (list them free with action "traits"), randomize, optional details.
- **Output:** Up to 4 takes; keep one with pixeldojo_save_character and it works as @Name everywhere.
- **Cost:** 5 credits for 4 takes; listing traits is free.

#### pixeldojo_perform

Make a saved character do a dance, a trend or a star moment as a share-ready 5 second video.

- **Input:** Saved character name or @Name plus a preset (AI Dance, Shoulder Shimmy, Catwalk, Red Carpet).
- **Output:** Video URL or an async job handoff.
- **Cost:** The preset's engine rate shown in the listing; charged only on success. Listing presets is free.

#### pixeldojo_upscale

Increase image resolution with conservative or creative enhancement, or upscale a video clip.

- **Input:** Image URL (or a video URL plus its length in seconds); optional upscaler and scale factor.
- **Output:** Upscaled image or video URL, or an async job handoff.
- **Cost:** Selected upscaler rate; charged only on success.

#### pixeldojo_caption

Burn animated word-by-word captions onto a video, placed clear of the TikTok, Reels and Shorts buttons.

- **Input:** Video URL with speech; optional style (pop, highlighter, clean) and highlight color.
- **Output:** Captioned video URL or an async job handoff.
- **Cost:** 5 credits per video; a clip with no speech is refused uncharged.

#### pixeldojo_overlay

Add ad text layouts to a video: hook title, lower-third callout, review card, progress bar, countdown timer, price tag, offer badge and a branded end card.

- **Input:** Video URL plus any of: hook, callout, review, progress bar, countdown, price tag, offer, end card (headline, button, web address, logo); brand color.
- **Output:** Branded video URL or an async job handoff.
- **Cost:** 2 credits per video; charged only on success.

#### pixeldojo_effects

Find one-click effects: 283 video effects (AI Hug, Earth Zoom In), 30 photo effects (action figure, Ghibli style, sticker) and one-job tools (watermark, object or background removal, headshots, restoration).

- **Input:** Optional search words, family (video-effect, photo-effect, tool) or category.
- **Output:** Each effect's slug, inputs and credit price.
- **Cost:** Free; no generation credits.

#### pixeldojo_effect

Run one effect on your photos with its prompt built in: a 5 second clip for video effects, a styled image for photo effects and tools.

- **Input:** Effect slug plus one or two photo URLs (local paths with the local npx install), and text for tools that ask for it.
- **Output:** Image or video URL, or an async job handoff for clips.
- **Cost:** The effect's engine rate shown in the listing; charged only on success.

#### pixeldojo_audio

Create narration or a complete audio scene with dialogue, effects, and music.

- **Input:** Script or scene prompt; optional voice, up to 3 hosted reference clip URLs, format, and speed.
- **Output:** Audio URL or a job ID and status URL.
- **Cost:** Seed Audio or text-to-speech model rate; charged only on success.

### Produce

#### pixeldojo_storyboard

Generate one video storyboard preview from one scene brief.

- **Input:** Brief; optional video model, aspect ratio, and duration.
- **Output:** One video preview URL or an async job handoff.
- **Cost:** One video generation at the selected model rate. Use film for multi-shot work.

#### pixeldojo_ad

Turn a product URL or photos into one rendered video ad with voiceover.

- **Input:** Product, style, and optional presenter, location, hook, script, quality, and duration.
- **Output:** Rendered ad URL or a job ID and status URL.
- **Cost:** Varies by engine, quality, resolution, and 4 to 15 second duration.

#### pixeldojo_marketing

Static ads, product shots, posters and marketplace listings from templates, motion graphics with exact text, and the brand end card.

- **Input:** Template, product URL or photos, headline and selling points; or a motion template with its text; or a finished ad for the end card.
- **Output:** Image or video URLs, or job IDs to check.
- **Cost:** Images at the engine rate (1.5 to 4.5 credits each); motion graphics 2 credits; end card 1 credit per 30 s. Listing templates is free.

#### pixeldojo_brand_kit

Import your logo, colors, fonts, voice and selling points from your website once; every ad and template uses them.

- **Input:** Your website, or the fields to change.
- **Output:** The saved brand kit.
- **Cost:** Free.

#### pixeldojo_film

Plan and produce a multi-shot short film with dialogue, score, and stitched export.

- **Input:** Idea or script, look, aspect ratio, and target length.
- **Output:** Free plan and estimate first; then film workspace and final video URL.
- **Cost:** Planning is free and quotes the cost first; production is billed per shot plus the soundtrack.

#### pixeldojo_campaign

Produce a hero image, lifestyle variants, and an optional vertical launch video.

- **Input:** Product URL/profile, tone, 1 to 8 variants, and video options.
- **Output:** Campaign ID plus an ordered asset set.
- **Cost:** Hero, lifestyle shots, and video are each billed at their model rate; the total shows in campaign status.

#### pixeldojo_video

Change, move, or extend a video you already have: restyle a clip, put a character into it, or lengthen it.

- **Input:** Verb (change, move, or extend), source video URL, prompt; optional reference images, clip length in seconds, and engine.
- **Output:** Edited video URL or an async job handoff.
- **Cost:** Selected engine rate, metered by clip length on most engines; charged only on success.

#### pixeldojo_episode

Make a finished narrated faceless video (explainer, history, kids story) from one topic.

- **Input:** Topic; optional category, visual style, aspect ratio, 60 to 300 second length, voice, and music.
- **Output:** Free script and credit quote first; then the finished video URL, saved to your Library.
- **Cost:** Planning is free; production is charged step by step at the same prices as Faceless Studio.

### Bring inputs

#### pixeldojo_upload

Upload a local image or video so another skill can use it by URL.

- **Input:** Absolute local file path (local npx install only; the hosted server takes URLs).
- **Output:** Temporary public URL that expires after about 24 hours.
- **Cost:** Free; no generation credits.

#### pixeldojo_from_url

Extract a structured product profile from a public product page.

- **Input:** Product-page URL.
- **Output:** Name, description, image URLs, and source metadata.
- **Cost:** Free; no generation credits.

### Manage

#### pixeldojo_status

Check a single long-running generation job.

- **Input:** Job ID returned by another skill.
- **Output:** Current state, failure/refund detail, or completed asset URLs.
- **Cost:** Free; polling never consumes generation credits.

#### pixeldojo_campaign_status

Check all sub-jobs in a campaign.

- **Input:** Campaign ID returned by pixeldojo_campaign.
- **Output:** Progress, warnings, total charged credits, and completed assets.
- **Cost:** Free; polling never consumes generation credits.

#### pixeldojo_library

Find permanent Library items and recent API/MCP generations.

- **Input:** Optional prompt query, model, modality, and result limit.
- **Output:** Reusable asset URLs with source and creation metadata.
- **Cost:** Free and read-only.

#### pixeldojo_save_workflow

Save a named multi-step skill chain for reuse.

- **Input:** Workflow name and ordered skill steps; {{prev}} can feed the prior result forward.
- **Output:** Saved workflow definition.
- **Cost:** Saving is free; generations run later use normal model rates.

#### pixeldojo_run_workflow

Run a previously saved workflow with new inputs.

- **Input:** Workflow name plus values for its input placeholders.
- **Output:** Final result, or a handoff when a step needs more time.
- **Cost:** Sum of the generation steps; polling and orchestration are free.

#### pixeldojo_list_workflows

List saved workflows before choosing one to run.

- **Input:** No required input.
- **Output:** Workflow names and saved step definitions.
- **Cost:** Free and read-only.

## How It Works

1. **Install MCP** with `npx @pixeldojo/mcp init` (or grab the SDK at https://www.npmjs.com/package/@pixeldojo/sdk).
2. **Add your API key** -- get one at https://pixeldojo.ai/api-platform/api-keys
3. **Your agent creates media** -- it calls the API, polls for results, and gets back image/video URLs.

## Authentication

```
Authorization: Bearer pd_your_api_key
```

## API Endpoints

- `GET /api/v1/models` -- Public discovery endpoint for all enabled image and video models.
- `GET /api/v1/models/{apiId}` -- Fetch model capabilities, parameters, and the canonical request schema for one model.
- `GET /api/v1/models/{apiId}/schema` -- Return the model request schema as JSON so agents and SDKs can build valid payloads.
- `POST /api/v1/models/{apiId}/run` -- Submit an async job for any image or video model. Match the request body to the schema from /models/{apiId}/schema.
- `GET /api/v1/jobs` -- List recent jobs for the authenticated API key owner with optional filters.
- `GET /api/v1/jobs/{jobId}` -- Check job status and retrieve outputs, asset references, and webhook delivery state when complete.
- `GET /api/v1/jobs/{jobId}/webhook` -- Inspect webhook configuration and delivery status for a job.
- `POST /api/v1/jobs/{jobId}/webhook` -- Redeliver the terminal webhook for a completed or failed job.
- `POST /api/v1/upload` -- Upload a local image or video and get back a public URL on the 24-hour temp bucket. Pass the returned URL as a reference image in any /run call. Bridges "user has a local file" → "API needs a URL" for agentic workflows.
- `GET /api/v1/library` -- Search the key owner's media library: saved Library items (permanent) plus recent generations, newest first. Query params: q (prompt substring), model (apiId), modality (image|video|audio), limit (1-50).
- `GET /api/v1/workflows` -- List the key owner's named multi-step skill chains. POST to the same path with {name, description?, steps:[{skill, args}]} to save one (upserts by name). Steps may reference {{input.<key>}} and {{prev}}.
- `POST /api/mcp` -- Streamable-HTTP MCP server carrying every named skill. Connect with OAuth (your client opens a browser to approve; no API key) or send Authorization: Bearer pd_your_key. Discovery: /.well-known/oauth-protected-resource/api/mcp.

Full model list: `GET https://pixeldojo.ai/api/v1/models`

## Code Examples

### MCP

```shell
# 1. Print the ready-to-paste MCP config for Claude Code / Cursor
npx @pixeldojo/mcp init

# 2. Set your API key
export PIXELDOJO_API_KEY=pd_your_api_key

# 3. Add the config to your client and restart it. It now has these tools:
#    pixeldojo_generate        Create a new image or video (with preset)
#    pixeldojo_edit            Edit an image with a text instruction
#    pixeldojo_character       Repeat a reference character across scenes
#    pixeldojo_build_character Build an AI influencer from traits (no photos)
#    pixeldojo_perform         Make a saved character dance or do a trend
#    pixeldojo_storyboard      One video shot preview from one brief
#    pixeldojo_upscale         Enhance an image or video clip
#    pixeldojo_caption         Animated word-by-word captions on a video
#    pixeldojo_overlay         Offer callout and branded end card on a video
#    pixeldojo_audio           Voices + effects + music in one clip
#    pixeldojo_effects         List one-click video + photo effects and tools
#    pixeldojo_effect          Run one effect on your photos (AI Hug, action figure)
#    pixeldojo_ad              Product -> rendered video ad
#    pixeldojo_film            Idea -> planned and produced short film
#    pixeldojo_video           Change, move or extend an existing clip
#    pixeldojo_episode         Topic -> narrated faceless video
#    pixeldojo_campaign        Product -> hero + lifestyle + video package
#    pixeldojo_from_url        Product URL -> structured profile
#    pixeldojo_upload          Local file -> temporary 24h public URL (local install)
#    pixeldojo_library         Search saved Library items + recent generations
#    pixeldojo_save_workflow   Save a reusable multi-step chain
#    pixeldojo_run_workflow    Run a saved chain with new inputs
#    pixeldojo_list_workflows  List saved chains
#    pixeldojo_status          Poll a long-running job
#    pixeldojo_campaign_status Poll a campaign and its sub-jobs

# No key needed for the hosted server: https://pixeldojo.ai/mcp (browser sign-in)
# Get an API key: https://pixeldojo.ai/api-platform/api-keys
```

### TypeScript SDK

```typescript
import { PixelDojoClient } from "@pixeldojo/sdk";

const pd = new PixelDojoClient({ apiKey: "pd_your_api_key" });

// Generate an image and wait for the result
const job = await pd.generate("google-nano-banana", {
  prompt: "A fantasy castle on a cliff at sunset",
  aspect_ratio: "16:9",
});

console.log(job.assets[0].url);
```

### Python

```python
import requests, time

API_KEY = "pd_your_api_key"

# Submit a generation job
job = requests.post(
    "https://pixeldojo.ai/api/v1/models/google-nano-banana/run",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"prompt": "A fantasy castle on a cliff at sunset"}
).json()

# Poll until the image is ready
while True:
    result = requests.get(
        job["statusUrl"],
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()
    if result["status"] == "completed":
        print("Image URL:", result["output"]["images"][0])
        break
    time.sleep(2)
```

### cURL

```bash
# Submit a job
curl -X POST "https://pixeldojo.ai/api/v1/models/google-nano-banana/run" \
  -H "Authorization: Bearer pd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A fantasy castle on a cliff at sunset"}'

# Poll for results
curl "https://pixeldojo.ai/api/v1/jobs/job_abc123" \
  -H "Authorization: Bearer pd_your_api_key"
```

## Available Models (165 total)

### Image Models

- **FLUX 3 Image** (`flux-3-image`) -- Black Forest Labs FLUX 3: photoreal text-to-image up to 4K, edits with up to 10 reference images, and web-grounded generation for real products and places. (1 credit) [photorealism, editing, product-photography, marketing]
- **Ideogram 4.5** (`ideogram-4-5`) -- Ideogram 4.5: best-in-class text rendering, posters, logos and photoreal images, plus natural-language edits and Precise Edit that changes only what you ask. (2 credits) [marketing, text-rendering, editing, photorealism]
- **Bria 3.2** (`bria-3-2`) -- Bria 3.2: text-to-image with 9 aspect ratio presets at 1K resolution, optional image and prompt enhancement, and photography/art medium hints. (1 credit) [photorealism, artistic, marketing]
- **Change Camera Angle** (`change-camera-angle`) -- Camera-aware editing via Qwen Image Edit with multi-angle LoRA. 360° orbit, tilt, and zoom. (1 credit) [editing]
- **Clarity Pro** (`clarity-pro-upscaler`) -- Clarity Pro Upscaler via Replicate. Photorealistic upscaling with identity preservation and creative control. Up to 16× and 64 megapixels. (4 credits) [upscale, photorealism]
- **Consistent Characters** (`consistent-characters`) -- Generate consistent character variations with FLUX Kontext, Nano Banana Pro/2, Flux 2 Dev, Qwen Image 2 Pro, or Grok Imagine. (1.25 credits) [character]
- **Creative Upscaler** (`creative-upscale`) -- Clarity Upscaler (creative upscale) via Replicate. Boost detail with stable-diffusion refinement. (2.5 credits) [upscale]
- **Ernie** (`ernie`) -- Baidu Ernie text-to-image. Multilingual prompts and built-in prompt expansion. (1 credit) [photorealism, marketing]

### Video Models

- **FLUX 3 Video** (`flux-3-video`) -- FLUX 3 Video generation. Text-to-video or image-to-video up to 20 seconds with synchronized audio, or extend and transform an existing clip. (25 credits) [video]
- **Gemini Omni Flash 1.2** (`google-gemini-omni-flash`) -- Google Gemini Omni Flash 1.2: text, frames, references, or a source video into 3–15s clips with native audio at 360p to 4K. First/last frame, reference images and videos, edit or extend a clip. (24 credits) [video, cinematic]
- **Grok R2V** (`grok-r2v`) -- xAI Grok Imagine reference-to-video via Replicate. 1 to 7 reference images plus prompt for 1 to 10 second clips at 480p or 720p. (10 credits) [video, character]
- **Grok Video Extend** (`grok-video-extend`) -- xAI Grok Imagine video extension. Continue an existing MP4 with a prompt-directed extension (2 to 10 seconds). (1.5 credits/sec) [video, editing]
- **Hailuo Standard** (`hailuo-standard`) -- Premium quality text-to-video and image-to-video (8 credits) [video, marketing]
- **Hailuo Fast** (`hailuo-fast`) -- Fast image-to-video generation (4 credits) [video, marketing]

Browse all models: https://pixeldojo.ai/api-platform

## Error Codes

| Code | Status | Message |
|------|--------|---------|
| `unauthorized` | 401 | Missing or invalid API key |
| `invalid_json` | 400 | Invalid JSON in request body |
| `validation_error` | 400 | Input validation failed |
| `not_found` | 404 | Model or job not found |
| `insufficient_credits` | 402 | Insufficient credits |
| `credit_error` | 500 | Failed to deduct credits |
| `submission_failed` | 500 | Failed to submit job |
| `expired` | 410 | Job has expired |
| `internal_error` | 500 | Internal server error |

## Where It Works

- **OpenClaw / ClawHub** -- Install the skill and your agent gets structured tool access.
- **MCP & Chat Agents** -- Any MCP-compatible agent or assistant can call the same endpoints.
- **Automation & Workflows** -- Wire generation into pipelines with polling or webhooks.

## Resources

- Install skill: https://clawhub.ai/blovett80/pixeldojo
- API docs: https://pixeldojo.ai/api-platform/documentation
- API keys: https://pixeldojo.ai/api-platform/api-keys
- LLM docs: https://pixeldojo.ai/llm.txt
- OpenAPI spec: https://pixeldojo.ai/api/openapi
- AI plugin manifest: https://pixeldojo.ai/.well-known/ai-plugin.json
- ComfyUI plugin: https://github.com/blovett80/ComfyUI-PixelDojo