magnific-studio

name

magnific-studio

description

Magnific Studio — generate AI images and upscale via the Freepik / Magnific REST API. Use when the user wants to generate an AI image, hero visual, banner background, illustration, or texture from a text prompt, or to upscale/enhance an existing image. Triggers on "Magnific", "Freepik", "generate an image", "AI background", "AI hero visual", "text-to-image", "upscale this image". Not for branded social posts or presentations (canva-studio) and not for UI mockups (figma-studio). Reads the API key from ~/.claude/freepik.env (FREEPIK_API_KEY) so it works across all sessions.

Magnific Studio — AI image generation & upscaling

Wraps the Freepik / Magnific REST API so any Claude Code session can generate AI imagery without an MCP server. The API key lives once in ~/.claude/freepik.env as FREEPIK_API_KEY=... (perms 600) and the script reads it automatically. (The env file keeps the freepik name on purpose — the key really is a Freepik API key, and existing machines already have it.)

When to use

• Generate a hero visual / banner background / illustration / texture / pattern from a text prompt (text-to-image, synchronous — returns the image directly).
• The user mentions Freepik, Magnific, "AI background", "generate an image", or "upscale this image".

Generate (text-to-image, synchronous)

# <skill-dir> = this skill's base directory, announced when the skill loads.
# Plugin installs live in the plugin cache; only the install.sh symlink flow
# uses ~/.claude/skills/magnific-studio — so never hardcode that path.
python3 <skill-dir>/scripts/generate.py \
  --prompt "abstract teal and indigo network mesh on dark navy, cinematic, no text" \
  --size widescreen_16_9 --num 2 \
  --out /path/to/output-dir

• --size options: square_1_1, widescreen_16_9, social_story_9_16, classic_4_3, traditional_3_4, standard_3_2, portrait_2_3, social_post_4_5, horizontal_2_1, vertical_1_2 (default widescreen_16_9).
• --num 1-4 (default 1). Writes freepik-<timestamp>-<i>.png to --out.
• Prints the saved file paths. Costs API credits — keep --num small while iterating.

Prompt tips: describe subject, palette, lighting, mood, composition. For banner backgrounds add no text, no letters, no words (overlay text in HTML/CSS afterwards), and steer composition (subject on the right, left side dark negative space) so headline text stays legible.

Upscale (Magnific, async)

python3 <skill-dir>/scripts/upscale.py \
  --image /path/to/input.png \
  --scale 2x \
  --out /path/to/output-dir

• --scale: 2x / 4x / 8x / 16x (engine-dependent; default 2x).
• Async under the hood: submits a task and polls until done (--timeout seconds, default 300). Writes upscaled-<timestamp>-<i>.png to --out and prints the saved paths.

Compose into a banner

Generate the background → set it as a full-bleed background-image in an HTML banner → add a dark side-gradient overlay for text legibility → screenshot with headless Chrome at exact dimensions (HTML→PNG export).

Notes

• No webhook needed. Text-to-image is synchronous. Async endpoints (Mystic, Magnific upscale) return a task_id; poll the status endpoint rather than using webhooks (no public callback URL on a local machine). A FREEPIK_WEBHOOK_SECRET in the env file is optional and only used if you ever run a public webhook receiver.
• Never print the API key. The script reads it from the env file silently.