pixelmuse-generate

Category: Content & Multimedia | Uploader: starmorph | Downloads: 0 | Version: v1.0（Latest）

Generate images using the Pixelmuse API. Use when the user says 'generate image', 'create image', 'pixelmuse', 'generate thumbnail', 'create thumbnail', 'make an image', 'AI image', 'generate art', 'nano banana', 'nanobanana', 'flux', 'recraft', 'imagen', or wants to create any image using AI image generation. Also use when the user provides a prompt and wants it turned into an image.

Changelog: Source: GitHub https://github.com/starmorph/pixelmuse-cli

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 568 B
  - 📄 security.yml 486 B
📁 assets/
- 📁 demos/
  - 📄 account-models.gif 686.6 KB
  - 📄 cli-generate.gif 1.0 MB
  - 📄 help.gif 449.2 KB
  - 📄 tui-demo.gif 823.9 KB
  - 📄 tui-generate.gif 890.9 KB
- 📄 banner.png 458.2 KB
📁 src/
- 📁 components/
  - 📄 GenerationProgress.tsx 955 B
  - 📄 Header.tsx 783 B
  - 📄 ImageGrid.tsx 2.4 KB
  - 📄 ImagePreview.tsx 1.3 KB
  - 📄 ModelTable.tsx 1.3 KB
  - 📄 StatusBar.tsx 661 B
- 📁 core/
  - 📄 auth.test.ts 814 B
  - 📄 auth.ts 2.0 KB
  - 📄 build.test.ts 851 B
  - 📄 client.ts 5.8 KB
  - 📄 config.ts 2.8 KB
  - 📄 device-auth.ts 3.2 KB
  - 📄 generate.ts 2.6 KB
  - 📄 image.ts 2.1 KB
  - 📄 index.ts 1.1 KB
  - 📄 keyring-node.d.ts 274 B
  - 📄 mcp-config.ts 1.8 KB
  - 📄 polling.ts 1.9 KB
  - 📄 prompts.test.ts 1.6 KB
  - 📄 prompts.ts 2.3 KB
  - 📄 types.test.ts 693 B
  - 📄 types.ts 3.0 KB
  - 📄 utils.test.ts 1.1 KB
  - 📄 utils.ts 431 B
- 📁 hooks/
  - 📄 useApi.ts 292 B
  - 📄 useAuth.ts 2.5 KB
  - 📄 useConfig.ts 452 B
  - 📄 useRouter.ts 1.5 KB
- 📁 mcp/
  - 📄 server.ts 4.9 KB
- 📁 screens/
  - 📄 Account.tsx 2.6 KB
  - 📄 BuyCredits.tsx 2.1 KB
  - 📄 Gallery.tsx 2.1 KB
  - 📄 GalleryDetail.tsx 3.5 KB
  - 📄 Generate.tsx 7.1 KB
  - 📄 Home.tsx 1.7 KB
  - 📄 Login.tsx 1.3 KB
  - 📄 Models.tsx 2.1 KB
  - 📄 PromptEditor.tsx 3.1 KB
  - 📄 Prompts.tsx 2.2 KB
- 📄 app.tsx 4.2 KB
- 📄 cli.ts 30.4 KB
- 📄 tui.tsx 2.1 KB
📄 .gitignore 60 B
📄 eslint.config.js 719 B
📄 LICENSE 3.9 KB
📄 llms.txt 3.6 KB
📄 package.json 2.1 KB
📄 pnpm-lock.yaml 100.4 KB
📄 README.md 8.9 KB
📄 SKILL.md 6.4 KB
📄 tsconfig.json 447 B
📄 tsup.config.ts 452 B
📄 vitest.config.ts 179 B

SKILL.md

---
name: pixelmuse-generate
description: |
  Generate images using the Pixelmuse API. Use when the user says 'generate image', 'create image',
  'pixelmuse', 'generate thumbnail', 'create thumbnail', 'make an image', 'AI image', 'generate art',
  'nano banana', 'nanobanana', 'flux', 'recraft', 'imagen', or wants to create any image
  using AI image generation. Also use when the user provides a prompt and wants it turned into an image.
version: 1.1.0
---

# Pixelmuse Image Generation

Generate images via the Pixelmuse REST API at `https://www.pixelmuse.studio/api/v1/images`.

## Authentication

The API key must be set as the `PIXELMUSE_API_KEY` environment variable. Keys start with `pm_live_` or `pm_test_`.

**Setup:** Get your API key from [pixelmuse.studio/settings/api-keys](https://pixelmuse.studio/settings/api-keys), then add it to your shell profile:

```bash
export PIXELMUSE_API_KEY="pm_live_your_key_here"
```

Or add it to `~/.zsh_secrets`, `~/.env`, or your project's `.env.local`.

**Key resolution order** (use the first one found):

```bash
# 1. Environment variable (recommended)
API_KEY="$PIXELMUSE_API_KEY"

# 2. Fallback: read from a local .env.local if env var is not set
if [ -z "$API_KEY" ]; then
  API_KEY=$(grep 'PIXELMUSE_API_KEY' .env.local 2>/dev/null | cut -d'"' -f2)
fi
```

If no key is found, ask the user to set `PIXELMUSE_API_KEY`. They can get one at [pixelmuse.studio/settings/api-keys](https://pixelmuse.studio/settings/api-keys).

## Available Models

| Model ID | Name | Credits | Provider | Best For |
|----------|------|---------|----------|----------|
| `nano-banana-2` | Nano Banana 2 | 1 | Gemini | Speed, text rendering, world knowledge (DEFAULT) |
| `nano-banana-pro` | Nano Banana Pro | 4 | Gemini | Text rendering, real-time info, multi-image editing |
| `flux-schnell` | Flux Schnell | 1 | Replicate | Quick mockups, ideation |
| `imagen-3` | Google Imagen 3 | 1 | Gemini | Realistic photos, complex compositions |
| `recraft-v4` | Recraft V4 | 1 | Replicate | Typography, design, composition |
| `recraft-v4-pro` | Recraft V4 Pro | 7 | Replicate | High-res design, art direction |

**Default model:** `nano-banana-2` (fast, 1 credit, good text rendering)

## Aspect Ratios

Supported: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:5`, `5:4`, `3:4`, `4:3`, `21:9`, `9:21`

Common use cases:
- **Blog thumbnails / OG images:** `16:9`
- **Social media posts:** `1:1`
- **Phone wallpapers / stories:** `9:16`
- **Portraits:** `2:3` or `4:5`
- **Ultrawide banners:** `21:9`

## Styles

Optional: `realistic`, `anime`, `artistic`, `none` (default: `none`)

## Generate an Image

Use `curl` via the Bash tool. **Always use `www.pixelmuse.studio`** (non-www redirects and drops the auth header).

**IMPORTANT:** Gemini models (nano-banana-2, nano-banana-pro, imagen-3) return inline results. Use `Prefer: wait=55` to get synchronous responses. Replicate models (flux-schnell, recraft-v4, etc.) return async predictions that require polling.

### Synchronous (Gemini models — recommended)

```bash
curl -s -X POST https://www.pixelmuse.studio/api/v1/images \
  -H "Authorization: Bearer $PIXELMUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=55" \
  -d '{
    "prompt": "YOUR PROMPT HERE",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9"
  }'
```

### Response Format

```json
{
  "id": "gemini_...",
  "status": "succeeded",
  "model": "nano-banana-2",
  "prompt": "...",
  "output": ["data:image/png;base64,..."],
  "credits_charged": 1,
  "error": null,
  "created_at": "2026-02-28T...",
  "completed_at": null
}
```

## Save the Image

The output is a base64 data URL. Extract and save it with Python:

```bash
curl -s -X POST https://www.pixelmuse.studio/api/v1/images \
  -H "Authorization: Bearer $PIXELMUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=55" \
  -d '{
    "prompt": "YOUR PROMPT HERE",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9"
  }' | python3 -c "
import json, sys, base64
data = json.load(sys.stdin)
if data['status'] == 'succeeded':
    b64 = data['output'][0].split(',', 1)[1]
    img = base64.b64decode(b64)
    with open('OUTPUT_PATH.png', 'wb') as f:
        f.write(img)
    print(f'Saved {len(img)} bytes')
else:
    print(f'Generation failed: {data.get(\"error\", data[\"status\"])}')
"
```

Replace `OUTPUT_PATH.png` with the desired file path.

## Workflow

1. **Ask user for prompt** if not provided. Help them refine it for best results.
2. **Resolve API key** — check `$PIXELMUSE_API_KEY` env var first, fall back to `.env.local` in the current directory, then ask the user to set it.
3. **Choose model** — default to `nano-banana-2` unless user specifies otherwise or needs specific capabilities.
4. **Choose aspect ratio** based on use case (blog thumbnail = `16:9`, social = `1:1`, etc.).
5. **Generate the image** using the curl command above.
6. **Save to disk** using the Python extraction script.
7. **Preview the image** using the Read tool so the user can see the result.
8. **Regenerate if needed** — offer to retry with a refined prompt if the user isn't happy.

## Prompt Tips

- Be specific and descriptive. Include style, lighting, composition, and mood.
- For blog thumbnails: include the topic visually, use dark backgrounds for dev content.
- For text in images: Nano Banana 2 is best at rendering text accurately.
- Avoid prompts that violate content policy (NSFW, violence, real people).

## Checking Account Balance

```bash
curl -s https://www.pixelmuse.studio/api/v1/account \
  -H "Authorization: Bearer $PIXELMUSE_API_KEY" | python3 -m json.tool
```

## Async Models (Replicate — flux, recraft)

These return `202` with `status: "processing"`. Poll for completion:

```bash
# Generate (returns processing status with ID)
RESPONSE=$(curl -s -X POST https://www.pixelmuse.studio/api/v1/images \
  -H "Authorization: Bearer $PIXELMUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=55" \
  -d '{"prompt": "...", "model": "recraft-v4", "aspect_ratio": "1:1"}')

# Extract ID and poll
ID=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
curl -s "https://www.pixelmuse.studio/api/v1/images/$ID" \
  -H "Authorization: Bearer $PIXELMUSE_API_KEY" | python3 -m json.tool
```

Poll every 2-3 seconds until `status` is `succeeded` or `failed`. The `Prefer: wait=55` header makes the server wait up to 55 seconds before returning, which often avoids polling entirely.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

pixelmuse-generate

Directory Structure

SKILL.md

Report

Notice