---
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)

```bash
# <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)

```bash
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.