Freepik API: The Complete Guide (2026)

If you search "Freepik API," you'll probably land on two very different things: an API for searching and downloading Freepik's stock photos, vectors, and icons, and a separate endpoint called Mystic that generates brand new images from a text prompt. Most developers typing that search are actually looking for the second one. This guide covers both, but spends most of its time on Mystic, since that's what people usually mean.

One more thing before we start: in April 2026, Freepik rebranded its entire product line as Magnific, taking the name of the AI upscaler it had acquired back in 2024 and folding the stock library and AI generation tools under it too. The documentation is in the middle of migrating: most of docs.freepik.com still shows Freepik branding, api.freepik.com, and the x-freepik-api-key header, but a handful of reference pages already point to api.magnific.com with an x-magnific-api-key header instead. Both hosts are live right now and an existing key works on either, so if a request fails with an auth error, check your dashboard for which host and header name your specific key expects before assuming your code is wrong. This guide uses the Freepik-branded values shown on the main interactive API reference, since that's still what's consistent across most of the docs and what most people searching "Freepik API" expect, but expect the Magnific naming to take over fully at some point.

What Is the Freepik API?

The Freepik API is a REST API that gives programmatic access to two different things under one developer account:

Stock content search and download. You can search and pull licensed photos, vectors, icons, and templates from Freepik's library of 250 million plus assets, the same content you'd otherwise browse manually on freepik.com.

Mystic, Freepik's AI image generation engine. This is a text-to-image (and image-to-image) model built in-house by Freepik, not a wrapper around someone else's model. It's a separate product from the stock library, with its own endpoint and its own pricing.

When people search "Freepik API," they're almost always asking about Mystic and AI generation, not the stock search endpoints. The stock API is useful if you're building something like a design tool that needs licensed assets on demand, but it solves a different problem than image generation.

What You Can Do With It

Stock Content Endpoints

The stock side of the API lets you search Freepik's photo, vector, and icon libraries by keyword, filter by orientation, content type, or color, and then trigger a licensed download. Freepik requires you to call a download endpoint every time a user in your app actually uses an asset (setting it as a header image, dropping it into a blog post, and so on), even if you're caching the file locally. Skipping that reporting step is a licensing violation and can get your API access revoked.

Mystic AI Image Generation Endpoint

Mystic takes a text prompt and returns one or more generated images. It's not a single fixed model, it's a family of six style presets you choose between:

realism (the default): a more natural, less "AI-looking" color palette, especially strong for photography-style prompts

zen: smoother, cleaner, simpler compositions

flexible: better prompt adherence, leans a bit more saturated and HDR, good for illustrations and fantastical scenes

fluid: the most literal prompt-follower of the set, built on Google's Imagen 3 under the hood, though this means it's more conservative about flagging certain words

super_real: prioritizes realism above everything else

editorial_portraits: tuned specifically for close-up and medium-shot portraits, not great for wide shots

You can also feed Mystic a structure reference image (to control composition, like turning a sketch into a finished illustration) or a style reference image (to transfer a visual style), plus control resolution (1k, 2k, or 4k), aspect ratio, and how much creative detailing gets added at higher resolutions.

Freepik API Pricing

The Freepik API is pay-as-you-go with no subscription required. Pricing is split by service:

A "creation" is one generation call. New accounts get 5 EUR of free credit to test things out. Billing is usage-based and calculated monthly, with invoices generated on the 5th of the following month, and you can cap your spend with a monthly budget limit in the dashboard (500 EUR is the self-serve ceiling; higher limits require talking to sales). Rate limits are set per service as requests-per-minute/day and, for generation, images-per-minute/day, and they vary depending on which service you're calling.

Worth noting: this is Freepik's official developer API pricing, which is separate from the consumer subscription plans (now sold under the Magnific brand) you'd see if you just signed up on freepik.com or magnific.com to use the web app. Those consumer credits do not carry over to API usage.

Getting Your Freepik API Key

Go to the Freepik API dashboard and sign up or log in.

Generate an API key from the dashboard. Keys are tied to your account and billing.

Every request needs the key in the x-freepik-api-key header, not a Bearer token, which trips people up if they're used to OAuth-style APIs.

curl --request POST \
  --url https://api.freepik.com/v1/ai/mystic \
  --header 'Content-Type: application/json' \
  --header 'x-freepik-api-key: YOUR_API_KEY' \
  --data '{
    "prompt": "a cozy reading nook by a rainy window, warm lamp light",
    "resolution": "2k",
    "aspect_ratio": "widescreen_16_9",
    "model": "realism"
  }'

Official Freepik API vs. Using Apiframe

If you're already comparing Freepik to other AI image APIs, it's worth being upfront about one thing: as of this writing, Apiframe (which unifies models like Midjourney, Flux, Nano Banana, Seedream, Ideogram, Imagen, and GPT Image behind a single key and a single bill) doesn't yet include Freepik's Mystic model in its lineup. So if Mystic specifically is what you need, you'll be integrating directly with Freepik's API for now.

That said, the friction points people run into with the direct Freepik integration are real: a separate API key and billing relationship just for this one model, its own rate limits to track, and its own response format to parse. If your actual goal is "AI-generated images in my product" rather than "Mystic specifically," it's worth checking Apiframe's image models first. You get a comparable range of styles and quality tiers (realistic photography, illustration, portraits) across models like Nano Banana Pro and Seedream, all reachable through one X-API-Key header and one job-polling pattern, which cuts down on the integration work if you're already generating video or music through Apiframe elsewhere in your stack.

How to Call the Freepik API: Code Example

Mystic generation is asynchronous: you submit a request, get a task ID back, and poll (or use a webhook) until the image is ready.

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.freepik.com/v1/ai/mystic"

headers = {
    "Content-Type": "application/json",
    "x-freepik-api-key": API_KEY,
}

payload = {
    "prompt": "a cozy reading nook by a rainy window, warm lamp light",
    "resolution": "2k",
    "aspect_ratio": "widescreen_16_9",
    "model": "realism",
}

# 1. Submit the generation request
response = requests.post(BASE_URL, headers=headers, json=payload)
response.raise_for_status()
task_id = response.json()["data"]["task_id"]
print(f"Task submitted: {task_id}")

# 2. Poll for the result
status_url = f"{BASE_URL}/{task_id}"
while True:
    status_response = requests.get(status_url, headers=headers)
    data = status_response.json()["data"]

    if data["status"] == "COMPLETED":
        print("Generated images:", data["generated"])
        break
    elif data["status"] == "FAILED":
        print("Generation failed:", data)
        break

    time.sleep(3)

If you'd rather not poll, pass a webhook_url in the initial request and Freepik will call it when the task's status changes.

Common Errors and Rate Limits

429 Too Many Requests: you've hit the RPM or RPD (requests per minute/day) limit, or for generation specifically, the IPM/IPD (images per minute/day) limit. These vary by service tier, so check your dashboard for your current limits rather than assuming a fixed number.

400 Bad Request on structure_reference or style_reference: these fields expect base64-encoded image data, not a URL. Passing a raw URL is a common mistake.

Silent LoRA ignoring: if you're using LoRAs (via the @character_name prompt syntax or the styling.characters array) and also passing a structure_reference or style_reference, the LoRA gets silently ignored rather than throwing an error. Same goes for the fluid, flexible, super_real, and editorial_portraits models, which don't support LoRAs at all. Worth checking your output carefully if a character isn't showing up as expected.

NSFW filter can't be turned off by default. filter_nsfw is locked to true unless Freepik's support team has specifically authorized your account otherwise.

Freepik API Alternatives

If you're evaluating Freepik/Mystic against other options, a few adjacent APIs worth comparing:

Apiframe: not a Freepik alternative exactly, but a single API across many other image and video models (Midjourney, Flux, Nano Banana, Seedream, Imagen, GPT Image) if you want breadth rather than one specific stock-plus-AI provider.

Unsplash API / Pexels API: stock photo alternatives if you only need the stock side and don't need AI generation at all.

Direct model APIs (OpenAI's image API, Google's Imagen, Black Forest Labs' Flux): worth a look if you want a single model rather than Freepik's six-style Mystic family, though you'll be managing separate keys for each.

FAQ

Is the Freepik API free? New accounts get 5 EUR of free credit, but there's no permanently free tier beyond that. After the trial credit, it's pay-as-you-go.

Can output be used commercially? Yes, generated images can be used commercially under Freepik's licensing terms, though it's worth reading the specific license page rather than assuming, since terms can vary by content type and plan.

What resolutions does Mystic support? 1k, 2k, and 4k, set via the resolution parameter.

Does it support image editing or upscaling? Mystic itself is generation-focused, but Freepik's broader API suite includes separate image editing and upscaling endpoints (the Magnific upscaler is part of the same platform now, following the rebrand).

If you're building a product that needs more than one AI image model, or you're already pulling video and music generation into your stack, it's worth comparing what a unified API like Apiframe covers before committing to a single-provider integration.