Pixelbin

PixelBin Claude Skill

Turn Claude into a full media pipeline. Generate, transform, store, and deliver images & videos at scale using PixelBin.

When to use

• User wants to generate images (nanoBanana, nanoBanana 2, nanoBanana Pro)
• User wants to generate videos (Sora 2, Veo 3, Kling 3, Hailuo, Seedance, LTX-2, Wan)
• User wants to remove backgrounds, watermarks, or upscale images/videos in bulk
• User wants permanent CDN URLs for media
• User wants to build URL-based image transformations (resize, crop, format, quality, etc.)
• User wants to generate SEO content (titles, meta, FAQ schema, briefs)
• User wants to build a landing page with AI-generated images stitched together
• User mentions "PixelBin", "nano banana", "build a media pipeline", "bulk image processing"

First-run behaviour (IMPORTANT)

Read INTRO.md before responding. INTRO.md is the user-facing voice of this skill — match its tone and follow its "How Claude should respond" section.

If the user has already stated a clear goal (e.g. "generate 6 hero images for X", "remove backgrounds from these photos", "build a landing page for Y"):

1. Confirm .env and node_modules/ are ready (see Setup check below) — auto-fix silently if you can.
2. Confirm model + key options in ONE friendly line (don't make them write JSON — give a default they can accept with "go"):
   • Image gen: "Quick pick: nano banana 2 (default, balanced) or nano banana Pro (premium quality, slower)? Aspect: 1:1 / 16:9 / 9:16 / 4:5 (default 1:1). Resolution: 1K / 2K / 4K (default 2K). Or just say 'defaults' and I'll use nano banana 2 · 1:1 · 2K."
   • Video gen: "Quick pick: Veo 3 Fast (default, balanced cost), Veo 3 (premium), Sora 2 (with audio), Kling 3 (cinematic), or Hailuo 2.3 (1080p)? Duration: 4 / 6 / 8s (default 6). Aspect: 16:9 / 9:16 / 1:1 (default 16:9)."
   • Resize/format: safe to default silently → t.resize(...)~t.toFormat(f:webp)~t.compress().
   • If the user already specified everything in their prompt, skip the picker and just run.
3. Run the right scripts under the hood and hand back CDN URLs.

If the user is just exploring ("hi", "what can you do?", "help"):

1. Greet them and present the broad buckets from INTRO.md (image gen, image edit, transformation, AI cleanup, video, bulk, SEO, landing pages).
2. Show one concrete example prompt + a sample CDN URL from INTRO.md so it feels real and easy.
3. Invite them to just say what they want in plain English. No CLI talk.

Default to chat-first. Don't expose CLI flags, JOBS arrays, model names, or transform syntax unless the user asks "how does this work?". Run scripts silently; report results visually.

Handling images the user provides (CRITICAL)

When the user references an image, you must obtain it yourself — never ask them to "give me a file path" or "save it to Downloads". The image is already accessible to you in one of these forms:

Never say "the inline image isn't saved on disk, please paste the path" — that's a user-experience failure. Saving inline image bytes to disk is your job, not theirs.

Cost-aware path selection (CRITICAL)

Before reaching for a generation model, decide whether the task needs generation at all. Generation models are the most expensive op in the stack. For most product / e-commerce / variant tasks, you can do the same job with a cheap prediction + free URL transforms.

Decision tree

Cost ranking (rough, lower → cheaper)

1. URL transforms — free, no API call
2. Plugin transforms in URL (when activated) — free per request, included in plan
3. Predictions: erase_bg, wm_remove, vsr_upscale — small per-call credit cost
4. Image generation — nanoBanana_generate < nanoBanana2_generate < nanoBananaPro_generate
5. Video generation — most expensive op; always confirm before spending

Worked example — "Amazon + Shopify + Instagram-ready, white bg, 4K, 1:1 + 9:16"

Wrong (what NOT to do): regenerate each variant with nanoBanana — 12 outputs × generation cost, plus product hallucination risk.

Right (default behavior):

For each source image:
  1. urlUpload(source)                                        → CDN URL
  2. predictions.createAndWait({ name: 'erase_bg', input: { image: cdnUrl } })  → transparent PNG
  3. urlUpload(eraseBgOutput)                                 → CDN URL of transparent product
  4. Build transform URLs (no API call):
     • Amazon 1:1   t.extend(t:200,r:200,b:200,l:200,bc:ffffff)~t.resize(h:2048,w:2048)~t.toFormat(f:jpeg)~t.compress()
     • Shopify 1:1  t.extend(t:150,r:150,b:150,l:150,bc:ffffff)~t.resize(h:2048,w:2048)~t.toFormat(f:webp)~t.compress()
     • Instagram 9:16  t.extend(t:600,r:200,b:600,l:200,bc:ffffff)~t.resize(h:1920,w:1080)~t.toFormat(f:webp)~t.compress()

This costs ~1 prediction per source image, vs 3 generations per source. Same visual result, fraction of the credits, zero product drift.

When in doubt — ask the user

If a task is borderline (e.g. "make this look more premium" — could be a transform or a regen), say in one line: "I can either (a) clean + restyle the existing photo with bg-remove + transforms (~1 credit each, preserves the actual product) or (b) regenerate hero shots with nano banana 2 (higher cost, more creative freedom). Which do you want?"

Setup check (always do this first)

Before running any script, verify:

1. .env exists with PIXELBIN_API_TOKEN and PIXELBIN_CLOUD_NAME
2. npm install has been run (deps: @pixelbin/admin, dotenv)

If missing, walk the user through cp .env.example .env and link them to the API Token page and signup.

Core architecture

┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   GENERATE       │ →  │   STORE (DAM)    │ →  │   TRANSFORM      │
│   image-gen      │    │   assets.upload  │    │   URL params     │
│   video-gen      │    │   folders, tags  │    │   (free, chained)│
└──────────────────┘    └──────────────────┘    └──────────────────┘
                                  ↓
                         ┌──────────────────┐
                         │   DELIVER (CDN)  │
                         │  cdn.pixelbin.io │
                         └──────────────────┘

Two URL patterns:

• Original (no transform): https://cdn.pixelbin.io/v2/<CLOUD>/original/<path>/<file>.<ext>
• Transformed: https://cdn.pixelbin.io/v2/<CLOUD>/<t.preset(args)>/<path>/<file>.<ext>
  • Multiple transforms chained with ~: t.resize(h:1024,w:1024)~t.toFormat(f:webp)~t.compress()

Capabilities (high-level)

SEO + landing-page input model

When the user wants SEO content or a landing page, ALWAYS gather these before running anything:

1. Target keyword (required) — what to rank for.
2. Brand reference (strongly recommended) — either a --brand-url <url> OR --brand-files "<glob>" (CSS / HTML / JSX / MD). Without this, the page won't match the user's design.
3. Research reference (optional) — --research-url <url> of a competitor or top-ranking page for SERP-intent signal.
4. Voice description (optional) — --voice "<short description>".

scripts/seo-content.js produces brief.json. It includes design_system (palette / fonts / CSS vars / max-widths) extracted from the brand reference. Claude then reads the brief and writes page-spec.json. build-page.js consumes the design block in page-spec.json and applies it as CSS variables (--fg, --bg, --accent, --font-body, --font-heading, --container).

If the user does NOT provide a brand reference, ask for one before generating the page. Don't guess colors/fonts.

SDK pattern (memorize this)

const { PixelbinConfig, PixelbinClient } = require('@pixelbin/admin');

const pixelbin = new PixelbinClient(new PixelbinConfig({
    domain: 'https://api.pixelbin.io',
    apiSecret: process.env.PIXELBIN_API_TOKEN,
}));

// 1. GENERATE (any AI model — image OR video — same shape)
const r = await pixelbin.predictions.createAndWait({
    name: 'nanoBanana2_generate',          // or veo3_generate, sora2_generate, kling3_generate, etc.
    input: {
        prompt: '...',                     // required
        images: ['https://...'],           // optional, image-to-image / image-to-video
        aspect_ratio: '16:9',              // optional, model-dependent
        output_resolution: '2K',           // optional, image models only
        duration: 8,                       // optional, video models only
    },
});
// r.status === 'SUCCESS' → r.output[0] is a temp URL (~30-day retention)

// 2. UPLOAD (local file → permanent CDN URL)
const up = await pixelbin.assets.fileUpload({
    file: fs.createReadStream('./photo.jpg'),
    path: 'my-folder',
    name: 'hero',
    access: 'public-read',
    overwrite: true,
});
// up.path / up.format → build URL: cdn.pixelbin.io/v2/<CLOUD>/original/<up.path>/hero.<up.format>

// 3. URL UPLOAD (remote URL → permanent CDN URL)
const up2 = await pixelbin.assets.urlUpload({
    url: r.output[0],
    path: 'my-folder',
    name: 'ai-output-1',
    access: 'public-read',
    overwrite: true,
});

// 4. TRANSFORM (no API call — just build the URL)
const cdn = `https://cdn.pixelbin.io/v2/${CLOUD}/t.resize(h:2048,w:2048)~t.toFormat(f:webp)~t.compress()/my-folder/hero.png`;

Models reference

Image generation

Video generation (popular)

Full list: references/apis.md.

Common URL transformations

Basic transforms (always available — no plugin needed):

AI ops via plugins (require activation in console.pixelbin.io → Plugins) — identifiers: erase_bg, wm_remove, wmrPro_remove, wmrMax_remove, af_remove, ocr_extract, pr_tag, vsr_upscale, wmv_remove, pwr_remove. For features the user hasn't activated, fall back to the predictions API (pixelbin.predictions.createAndWait) — that always works.

Chain transforms with ~. Full catalog: references/transformations.md.

Error handling

Script conventions (when generating code)

• Use dotenv for credentials. Never hardcode tokens.
• Batch concurrency: 4 for generation, 5 for uploads.
• Persist progress to JSON after each batch (resumable).
• Use slug-safe name values (lowercase, hyphens, no spaces).
• Default access: 'public-read' unless the user wants signed URLs.

What NOT to do

• ❌ Don't suggest scraping / bulk-downloading from third-party sites
• ❌ Don't generate content with real, named individuals without consent
• ❌ Don't surface the user's API token in chat or logs
• ❌ Don't claim a transformation works without checking references/transformations.md

Files in this skill

• INTRO.md — first-run user walkthrough (READ THIS WHEN INVOKED)
• SKILL.md — this file
• README.md — public-facing repo readme
• SHOWCASE.md — sample gallery
• .env.example — credentials template
• package.json — deps
• scripts/ — runnable scripts (generate-image, generate-video, upload, transform, seo-content, build-page)
• references/ — apis.md, transformations.md, cdn.md, use-cases.md
• examples/ — ready-to-run sample job files