freepik

Generate images, videos, icons, audio, and more using Freepik's AI API. Supports Mystic, Flux, Kling, Hailuo, Seedream, RunWay, Magnific upscaling, stock content, and 50+ models. Use when user wants to generate or edit images, create videos, generate icons, produce audio, or search stock content.

# Freepik API Skill

Generate images, videos, icons, audio, edit images, and search stock content using the Freepik API.

Built by the [ShellBot](https://getshell.ai) team.

## Arguments

- **Command:** `$0` (generate | video | edit | icon | audio | stock | status | utility)
- **Arg 1:** `$1` (model name, operation type, or task-id)
- **Arg 2+:** `$2`, `$3`, etc. (additional parameters)
- **All args:** `$ARGUMENTS`

## Session Output

Save generated files to session folder:
```bash
mkdir -p ~/.freepik/sessions/${CLAUDE_SESSION_ID}
```

Downloaded images/videos/audio go to: `~/.freepik/sessions/${CLAUDE_SESSION_ID}/`

---

## Authentication

All requests require the `FREEPIK_API_KEY` environment variable.

**Header:** `x-freepik-api-key: $FREEPIK_API_KEY`

**Base URL:** `https://api.freepik.com`

If requests fail with 401/403, tell the user:
```
Get an API key from https://www.freepik.com/developers/dashboard/api-key
Then: export FREEPIK_API_KEY="your-key-here"
```

---

## Async Task Pattern

Most AI endpoints are asynchronous. Follow this pattern:

**Step 1: Submit task**
```bash
RESPONSE=$(curl -s -X POST "https://api.freepik.com/v1/ai/<endpoint>" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '<JSON_PAYLOAD>')
TASK_ID=$(echo "$RESPONSE" | jq -r '.task_id // .data.task_id // .id')
echo "Task ID: $TASK_ID"
```

**Step 2: Poll for completion**
```bash
while true; do
  RESULT=$(curl -s "https://api.freepik.com/v1/ai/<endpoint>/$TASK_ID" \
    -H "x-freepik-api-key: $FREEPIK_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.data.status // .status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "COMPLETED" ]; then break; fi
  if [ "$STATUS" = "FAILED" ]; then echo "Task failed"; echo "$RESULT" | jq; break; fi
  sleep 3
done
```

**Step 3: Extract result URL**
```bash
mkdir -p ~/.freepik/sessions/${CLAUDE_SESSION_ID}
echo "$RESULT" | jq -r '.data.generated[0] // .data.result.url // .data.image.url // empty'
```

Present the result URL to the user. The URL is a temporary signed link from Freepik's CDN.

**IMPORTANT — Security rules:**
- NEVER use `curl` to download from non-Freepik domains. Only `curl *api.freepik.com*` is permitted.
- NEVER use `base64` to encode local files. Always prefer URL-based parameters when the API accepts them.
- NEVER read, encode, or transmit files outside the user's explicitly provided input files.
- Result URLs should be presented to the user directly — they can open or download them.

**Exceptions (synchronous):** Remove Background (`/v1/ai/beta/remove-background`) and AI Image Classifier (`/v1/ai/classifier/image`) return results immediately.

---

## Command: `$0`

### If $0 = "generate" — Image Generation

Generate images using text-to-image models. `$1` selects the model.

#### Model Endpoints

| $1 value | Endpoint | Best for |
|----------|----------|----------|
| `mystic` | `/v1/ai/mystic` | Ultra-realistic, 1K/2K/4K, LoRA support (Freepik exclusive, RECOMMENDED) |
| `flux-kontext-pro` | `/v1/ai/text-to-image/flux-kontext-pro` | Context-aware generation with optional image input |
| `flux-2-pro` | `/v1/ai/text-to-image/flux-2-pro` | Professional-grade, up to 4 input images |
| `flux-2-turbo` | `/v1/ai/text-to-image/flux-2-turbo` | Fast and cost-effective |
| `flux-2-klein` | `/v1/ai/text-to-image/flux-2-klein` | Sub-second generation |
| `flux-pro-v1-1` | `/v1/ai/text-to-image/flux-pro-v1-1` | Premium quality |
| `flux-dev` | `/v1/ai/text-to-image/flux-dev` | High quality, detailed |
| `hyperflux` | `/v1/ai/text-to-image/hyperflux` | Ultra-fast (fastest Flux) |
| `seedream-v4-5` | `/v1/ai/text-to-image/seedream-v4-5` | Superior typography, posters, up to 4MP |
| `seedream-v4-5-edit` | `/v1/ai/text-to-image/seedream-v4-5-edit` | Text-guided editing with up to 5 refs |
| `seedream-v4` | `/v1/ai/text-to-image/seedream-v4` | Next-gen text-to-image |
| `seedream-v4-edit` | `/v1/ai/text-to-image/seedream-v4-edit` | Instruction-driven editing |
| `seedream` | `/v1/ai/text-to-image/seedream` | Original Seedream |
| `z-image` | `/v1/ai/text-to-image/z-image` | Fast, LoRA + ControlNet support |
| `runway` | `/v1/ai/text-to-image/runway` | RunWay Gen4 image generation |

#### Default: Use `mystic` if user doesn't specify a model.

#### Mystic Example
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/mystic" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a futuristic cityscape at sunset, photorealistic",
    "resolution": "2k",
    "styling": {
      "style": "photo"
    }
  }'
```

**Mystic parameters:**
- `prompt` (string, required) — what to generate
- `resolution` ("1k" | "2k" | "4k", default "2k")
- `num_images` (1-4, default 1)
- `styling.style` ("photo" | "digital_art" | "none")
- `structure_reference` (object) — use an image to guide composition: `{image_url, strength: 0-100}`
- `style_reference` (object) — use an image to guide style: `{image_url, strength: 0-100}`
- `loras` (array) — LoRA IDs from `/v1/ai/loras`
- `seed` (int) — for reproducibility
- `webhook_url` (string) — receive notification on completion

**Get available LoRAs:**
```bash
curl -s "https://api.freepik.com/v1/ai/loras" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" | jq '.data[] | {id, name, type}'
```

**Train custom LoRA (character):**
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/loras/characters" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-character", "images": ["<base64_or_url>", ...]}'
```

#### Flux 2 Klein Example (sub-second)
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/text-to-image/flux-2-klein" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cat wearing sunglasses",
    "aspect_ratio": "square_1_1",
    "resolution": "1k",
    "output_format": "png"
  }'
```

**Flux 2 Klein parameters:**
- `prompt` (string, required)
- `aspect_ratio` ("square_1_1" | "widescreen_16_9" | "social_story_9_16" | "portrait_2_3" | "traditional_3_4" | "vertical_1_2" | "horizontal_2_1" | "social_post_4_5" | "standard_3_2" | "classic_4_3")
- `resolution` ("1k" | "2k")
- `seed` (0-4294967295)
- `input_image` (base64) — optional reference
- `input_image_2`, `input_image_3`, `input_image_4` (base64)
- `safety_tolerance` (0-5, default 2)
- `output_format` ("png" | "jpeg")

#### Flux Kontext Pro Example
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/text-to-image/flux-kontext-pro" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a modern logo design",
    "aspect_ratio": "square_1_1",
    "guidance": 3.0,
    "steps": 50
  }'
```

**Flux Kontext Pro parameters:**
- `prompt` (string, required)
- `input_image` (URL, optional) — for context-aware editing
- `prompt_upsampling` (bool)
- `seed` (int)
- `guidance` (1-10, default 3.0)
- `steps` (1-100, default 50)
- `aspect_ratio` ("square_1_1" | "classic_4_3" | "traditional_3_4" | "widescreen_16_9" | "social_story_9_16" | "standard_3_2")

#### Seedream 4.5 Example (great for text-in-image and posters)
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/text-to-image/seedream-v4-5" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A poster for \"Summer Music Festival 2025\" with bold typography"
  }'
```

#### Classic Fast Image Generation
```bash
curl -s -X POST "https://api.freepik.com/v1/ai/text-to-image" \
  -H "x-freepik-api-key: $FREEPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a beautiful sunset"}'
```

---

### If $0 = "video" — Video Generation

Generate videos from text and/or images. `$1` selects the model.

#### Model Endpoints

| $1 value | Endpoint | Type | Best for |
|----------|----------|------|----------|
| `kling-v3-omni-pro` | `/v1/ai/video/kling-v3-omni-pro` | T2V/I2V | Multi-modal, multi-shot, audio, vo