DEV Community: Kodnex Technologies

Best Free Wallpaper APIs in 2026: NexWall vs Unsplash vs Pexels vs Pixabay vs Wallhaven

Kodnex Technologies — Tue, 06 Oct 2026 06:14:58 +0000

Disclosure up front: I build NexWall, one of the five APIs in this comparison. I've tried to be fair: the other four are well-established services, and for several use cases one of them is the better choice. I say where that applies.

Starter code: free, MIT-licensed examples for Flutter, Android Kotlin, React Native, Python and Next.js / Laravel / JavaScript.

If you're building a wallpaper app, a launcher theme, a "new tab" page, or a script that changes your desktop background every morning, you need images. Scraping is legally risky and fragile. Bundling a few hundred images into your APK gets stale quickly. A free wallpaper API solves both problems.

"Wallpaper API" covers two quite different kinds of service, though:

General stock-photo APIs (Unsplash, Pexels, Pixabay). These are huge libraries of photography. They aren't wallpaper-specific, but you can filter by orientation and search keywords.
Wallpaper-specific APIs (NexWall, Wallhaven). These have catalogs organized around wallpaper use: aspect ratios, resolutions, and wallpaper-style categories.

Here's how the five compare.

Quick comparison

	NexWall	Unsplash API	Pexels API	Pixabay API	Wallhaven API
Focus	Curated phone wallpapers (portrait 9:16)	General high-quality photography	General photos + videos	Photos, illustrations, vectors, videos	Community-uploaded desktop & phone wallpapers
Free tier	Yes: 100 req/day, 60 req/min	Yes (demo mode, then apply for production)	Yes	Yes (free key)	Yes (key optional for SFW content)
Auth	Bearer API key	Access key (OAuth for user actions)	API key header	API key query param	Optional API key
Attribution / usage rules	Governed by the NexWall Developer API License	Attribution + hotlinking + download-tracking guidelines	Attribution to Pexels and photographers requested	Display Pixabay attribution with results; caching and hotlinking rules	Varies per image; uploaders don't always hold rights
Max resolution	Up to 2160x3840 (4K portrait)	Original photo sizes (often very large)	Original sizes	Large sizes on request (some need approval)	Original upload sizes (often 4K+)
Categories	50+ curated wallpaper categories	Topics / collections	Collections	Category param	Categories (general/anime/people) + tags
Live / video wallpapers	Yes, looping MP4 (Ultra plan)	No	Yes (stock videos, not wallpaper loops)	Yes (stock videos)	No
Catalog size	Smaller, curated	Very large	Very large	Very large	Very large
Paid tiers	Pro $4.99/mo, Ultra $10.99/mo	API is free to use (check docs)	API is free to use (check docs)	API is free to use (check docs)	API is free to use (check docs)

Exact rate limits for the other services change over time, so check their current docs before relying on a number. I've avoided quoting limits I couldn't verify for this article.

Unsplash API

Best for: beautiful, high-end photography, and apps where photographer attribution fits the UX.

Unsplash has arguably the most aesthetically consistent large photo library on the web, and the API is mature and well documented. Search supports an orientation filter (portrait), so you can get phone-friendly results.

Things to know:

New apps start in a rate-limited demo mode. You apply for production access, and the app is reviewed against their guidelines.
The API guidelines require you to hotlink images from Unsplash's URLs (no re-hosting), attribute the photographer and Unsplash, and trigger the download endpoint when a user downloads or sets a photo.
It's a photography library. You won't find AMOLED blacks, abstract gradients, or "anime wallpaper" style content.

Verdict: Excellent if your app is photography-centric and you're happy to build attribution into the UI.

Pexels API

Best for: free photos and videos with a simple key and generous use.

Pexels offers a straightforward REST API with search, curated photos, and a video API. It supports orientation filters, and its src object returns multiple sizes (including portrait), which is convenient for phone layouts.

Things to know:

Pexels asks you to show a prominent link back to Pexels and to credit photographers where possible.
Default rate limits are hourly and monthly. Higher limits are available on request. Check their docs for the current numbers.
Like Unsplash, it's a general stock library rather than a wallpaper catalog.

Verdict: A great default for "I need nice images and maybe some video" with minimal friction.

Pixabay API

Best for: illustrations, vector art, and mixed media alongside photos.

Pixabay's API is free with a key, and it covers photos, illustrations, vectors, and videos. Filters include image_type, orientation, category, min_width/min_height, and safesearch.

Things to know:

It's rate limited per time window. Pixabay also asks you to cache API responses and not to permanently hotlink their images. Check their docs for the current specifics.
When you show search results from the API, you're expected to show where they came from (Pixabay).
Full-resolution originals may require approved access.

Verdict: Useful when you want illustrations or vectors and not just photography. Read the caching and hotlinking rules carefully before designing your architecture.

Wallhaven API

Best for: desktop wallpaper enthusiasts and huge, tag-rich community content.

Wallhaven is the closest thing to a "real" wallpaper community with a public API. Its search lets you filter by ratio (e.g. 9x16 for phones), minimum resolution (atleast), categories (general/anime/people), and purity (SFW/sketchy/NSFW). You need an API key only for NSFW content and account-specific settings.

Things to know:

Content is user-uploaded. Many wallpapers are fan art, game screenshots, or edits, and the uploader doesn't necessarily own the rights. For a personal desktop script that's usually fine. For a commercial app on the Play Store, it's a real licensing risk you need to evaluate yourself.
Make sure your requests filter purity to SFW if your app is for a general audience.
Rate limits are per minute. Check the docs.

Verdict: Fantastic catalog for personal projects and desktop tools. Think carefully before you build a monetized product on it.

NexWall

Best for: phone wallpaper apps that want curated, wallpaper-specific content and a clear commercial path.

Full disclosure again: this is the one I build. NexWall is a wallpaper REST API designed specifically for wallpaper apps rather than general imagery:

Portrait-first: 9:16 wallpapers up to 2160x3840 (4K UHD portrait), with thumbnails included in every record.
50+ curated categories (for example "AMOLED & Pure Black"). You can list them with GET /categories and filter with category_id.
Wallpaper-oriented feed options: sort=newest|oldest|popular|random, tag search, and pagination up to 100 per page.
Live wallpapers: looping MP4s via type=live on the Ultra plan.
Free tier: 100 requests/day, 60 requests/min, no credit card, non-premium categories.
Paid tiers: Pro ($4.99/mo or ₹399/mo) gives 10,000 req/day, all categories, and commercial monetization rights. Ultra ($10.99/mo or ₹899/mo) gives 50,000 req/day plus live MP4 wallpapers.
An OpenAPI 3.0 spec at https://nexwall.kodnextech.com/openapi.json, so you can import it into Postman or generate a client.

curl "https://nexwall.kodnextech.com/api/developer/v1/wallpapers?sort=popular&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Where NexWall is weaker (honestly):

It's newer and smaller. The catalog is curated, not crowd-sourced, so it's much smaller than Unsplash, Pexels, Pixabay, or Wallhaven. If you need millions of images or very niche search terms, the big libraries win.
The free tier is modest. 100 requests/day is enough to build and test, and with server-side caching a small app can stretch it. A popular app will need a paid plan or a caching proxy.
Portrait-first. Desktop/landscape wallpaper users are better served by Wallhaven's ratio filters, or you'll need to letterbox and blur the images yourself.
Premium categories and live wallpapers are paid, unlike the fully free stock APIs.
Monetized apps need a paid plan. Commercial deployment rights in Play Store / App Store apps (with AdMob or subscriptions) are part of Pro and Ultra, under the Developer API License.

Verdict: A good fit if you're building a phone wallpaper app and want wallpaper-native categories, consistent 4K portrait output, live wallpapers, and a clear commercial license, without building attribution UI around a stock-photo library.

Which one should you pick?

Your situation	Good choice
Photography-centric app, happy to show attribution	Unsplash
Need free photos and videos with minimal setup	Pexels
Need illustrations or vectors	Pixabay
Personal desktop wallpaper script, huge variety	Wallhaven (filter to SFW)
Phone wallpaper app with categories, 4K portrait, live wallpapers, commercial plan	NexWall
Not sure yet	Prototype with two of them behind a common interface and compare real results

That last row is worth taking seriously. Put your image source behind an interface such as WallpaperRepository.fetch(category, page) and you can switch providers, or combine them, without rewriting your UI.

Universal tips, whichever API you use

Never ship your API key in a client binary. Use a small backend proxy. It also lets you cache responses across users, which effectively multiplies any free tier.
Use thumbnails in grids. Load full-resolution files only on the detail screen or when setting the wallpaper.
Respect each provider's rules. That means attribution, hotlinking, caching, and download tracking. Breaking them is the quickest way to lose your key.
Handle 429 properly. Read Retry-After and back off. Don't hammer the API.
Check licensing for commercial apps. "Free to download" isn't the same as "licensed for use in my monetized app".

I work on NexWall. If you think I've misrepresented any of the other APIs, please say so in the comments and I'll correct it. I'd rather this comparison be accurate than flattering.

Links: NexWall docs · Free API key · Unsplash Developers · Pexels API · Pixabay API docs · Wallhaven API

A Cross-Platform Daily Wallpaper Changer in One Python Script (Windows, macOS, Linux)

Kodnex Technologies — Tue, 06 Oct 2026 05:56:52 +0000

Disclosure: I build NexWall, the wallpaper API this script uses. The OS-specific "set wallpaper" code works with any image file, so feel free to point it at a different source.

Full source code: kodnextechnologies/nexwall-python (MIT licensed)

Want your desktop background to change every morning without installing yet another background app? This guide builds a single Python script that:

Asks a wallpaper REST API for one random wallpaper (one request per day)
Downloads it
Fits it to your screen using a blurred-background "letterbox", because the source images are portrait
Sets it as the wallpaper on Windows, macOS, or Linux (GNOME, KDE, or feh)
Runs daily via Task Scheduler, launchd, or a systemd timer

The API

I'm using the NexWall free wallpaper API: 100 requests/day on the free tier, no credit card, and images up to 2160x3840. A daily changer uses one request per day, so the free tier is far more than enough.

Get a key at https://nexwall.kodnextech.com/developers/register, then:

pip install requests pillow

The call we need:

curl "https://nexwall.kodnextech.com/api/developer/v1/wallpapers?sort=random&per_page=1&type=image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

It returns {"data": [{ "id": ..., "image_url": "...", "resolution": "2160x3840", "tags": "...", ... }], ...}.

A note on aspect ratio

NexWall is portrait-first (9:16, built for phones). On a 16:9 monitor, stretching a portrait image looks terrible and cropping it loses most of the picture. So the script does what phone galleries do: it scales the image to cover the screen, blurs that as a background, and centres the full image on top. It looks surprisingly good, especially with AMOLED and minimal styles. If you'd rather not, set FIT_MODE=cover to simply centre-crop.

The script

Save as nexwall_daily.py:

#!/usr/bin/env python3
"""
Daily wallpaper changer using the NexWall wallpaper REST API.
Works on Windows, macOS, and Linux (GNOME, KDE Plasma, or feh).

Env vars:
  NEXWALL_API_KEY      (required)  your API key
  NEXWALL_CATEGORY_ID  (optional)  numeric category id, see GET /categories
  WALLPAPER_SIZE       (optional)  e.g. "2560x1440", default "1920x1080"
  FIT_MODE             (optional)  "blur" (default) or "cover"
"""
import ctypes
import os
import platform
import subprocess
import sys
from pathlib import Path

import requests
from PIL import Image, ImageFilter

API_BASE = "https://nexwall.kodnextech.com/api/developer/v1"
OUT_DIR = Path.home() / ".nexwall"
KEEP_FILES = 7


def fetch_random_wallpaper(api_key: str, category_id: str | None) -> dict:
    params = {"sort": "random", "per_page": 1, "type": "image"}
    if category_id:
        params["category_id"] = int(category_id)

    r = requests.get(
        f"{API_BASE}/wallpapers",
        headers={"Authorization": f"Bearer {api_key}", "Accept": "application/json"},
        params=params,
        timeout=15,
    )
    if r.status_code == 401:
        sys.exit("Invalid or missing API key (HTTP 401).")
    if r.status_code == 429:
        sys.exit(f"Rate limited. Retry after {r.headers.get('Retry-After', '?')} seconds.")
    r.raise_for_status()

    items = r.json().get("data", [])
    if not items:
        sys.exit("No wallpapers returned. Check the category id.")
    return items[0]


def download(url: str, dest: Path) -> Path:
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 16):
                f.write(chunk)
    return dest


def fit_to_screen(src: Path, dest: Path, size: tuple[int, int], mode: str) -> Path:
    W, H = size
    lanczos = Image.Resampling.LANCZOS
    with Image.open(src) as im:
        im = im.convert("RGB")

        # "cover": scale so the image fills the screen, then centre-crop.
        s = max(W / im.width, H / im.height)
        cover = im.resize((round(im.width * s), round(im.height * s)), lanczos)
        left, top = (cover.width - W) // 2, (cover.height - H) // 2
        cover = cover.crop((left, top, left + W, top + H))

        if mode == "cover":
            result = cover
        else:
            # "blur": blurred cover as background + full image centred on top.
            result = cover.filter(ImageFilter.GaussianBlur(40))
            s = min(W / im.width, H / im.height)
            fg = im.resize((round(im.width * s), round(im.height * s)), lanczos)
            result.paste(fg, ((W - fg.width) // 2, (H - fg.height) // 2))

        # JPEG: the most widely supported wallpaper format across desktops.
        result.save(dest, "JPEG", quality=92)
    return dest


def set_wallpaper(path: Path) -> None:
    path = path.resolve()
    system = platform.system()

    if system == "Windows":
        SPI_SETDESKWALLPAPER = 20
        SPIF_UPDATEINIFILE_SENDCHANGE = 0x01 | 0x02
        ok = ctypes.windll.user32.SystemParametersInfoW(
            SPI_SETDESKWALLPAPER, 0, str(path), SPIF_UPDATEINIFILE_SENDCHANGE
        )
        if not ok:
            raise OSError("SystemParametersInfoW failed")

    elif system == "Darwin":
        script = (
            'tell application "System Events" to tell every desktop '
            f'to set picture to POSIX file "{path}"'
        )
        subprocess.run(["osascript", "-e", script], check=True)

    else:  # Linux / BSD
        desktop = os.environ.get("XDG_CURRENT_DESKTOP", "").lower()
        uri = path.as_uri()
        if any(d in desktop for d in ("gnome", "unity", "cinnamon", "budgie")):
            base = ["gsettings", "set", "org.gnome.desktop.background"]
            subprocess.run(base + ["picture-uri", uri], check=True)
            # GNOME 42+ uses a separate key for dark mode; ignore if missing.
            subprocess.run(base + ["picture-uri-dark", uri], check=False)
            subprocess.run(base + ["picture-options", "zoom"], check=False)
        elif "kde" in desktop:
            subprocess.run(["plasma-apply-wallpaperimage", str(path)], check=True)
        else:
            subprocess.run(["feh", "--bg-fill", str(path)], check=True)


def cleanup(directory: Path, keep: int) -> None:
    files = sorted(directory.glob("wallpaper-*.jpg"), key=lambda p: p.stat().st_mtime)
    for old in files[:-keep]:
        old.unlink(missing_ok=True)


def main() -> None:
    api_key = os.environ.get("NEXWALL_API_KEY")
    if not api_key:
        sys.exit("Set NEXWALL_API_KEY first.")

    w, h = (int(x) for x in os.environ.get("WALLPAPER_SIZE", "1920x1080").lower().split("x"))
    mode = os.environ.get("FIT_MODE", "blur")
    OUT_DIR.mkdir(parents=True, exist_ok=True)

    wp = fetch_random_wallpaper(api_key, os.environ.get("NEXWALL_CATEGORY_ID"))
    raw = download(wp["image_url"], OUT_DIR / "download.tmp")

    # Unique filename per wallpaper: macOS caches by path and may not refresh otherwise.
    final = fit_to_screen(raw, OUT_DIR / f"wallpaper-{wp['id']}.jpg", (w, h), mode)
    raw.unlink(missing_ok=True)

    set_wallpaper(final)
    cleanup(OUT_DIR, KEEP_FILES)
    print(f"Set wallpaper #{wp['id']} ({wp.get('resolution')}) tags: {wp.get('tags')}")


if __name__ == "__main__":
    main()

(Requires Python 3.10+ for the str | None hints. Pillow wheels include WebP support, which matters because the API serves .webp files.)

Try it once by hand:

# macOS / Linux
export NEXWALL_API_KEY=YOUR_API_KEY
python3 nexwall_daily.py

# Windows (PowerShell)
$env:NEXWALL_API_KEY = "YOUR_API_KEY"
python nexwall_daily.py

Picking a category

List the categories your plan can access:

curl "https://nexwall.kodnextech.com/api/developer/v1/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Accept: application/json"

Pick an id (for example, the "AMOLED & Pure Black" category) and set NEXWALL_CATEGORY_ID to it. The free plan covers the non-premium categories.

Running it every day

Windows: Task Scheduler

Store the key as a persistent user environment variable, then create a daily task. Use pythonw.exe so no console window flashes:

setx NEXWALL_API_KEY "YOUR_API_KEY"
setx WALLPAPER_SIZE "2560x1440"

schtasks /Create /SC DAILY /ST 08:00 /TN "NexWall Daily Wallpaper" `
  /TR "\"C:\Path\To\pythonw.exe\" \"C:\Path\To\nexwall_daily.py\""

(Open a new terminal after setx. It doesn't affect the current session.)

macOS: launchd

~/Library/LaunchAgents/com.example.nexwall.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.example.nexwall</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/python3</string>
    <string>/Users/you/scripts/nexwall_daily.py</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>NEXWALL_API_KEY</key><string>YOUR_API_KEY</string>
    <key>WALLPAPER_SIZE</key><string>2880x1800</string>
  </dict>
  <key>StartCalendarInterval</key>
  <dict><key>Hour</key><integer>8</integer><key>Minute</key><integer>0</integer></dict>
  <key>RunAtLoad</key><true/>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.example.nexwall.plist

The first run will ask you to allow the process to control "System Events". Approve it once. Use the Python interpreter that actually has requests and pillow installed (check with which python3).

Linux: systemd user timer

Use a user timer rather than cron. User services run inside your session and can reach the D-Bus session bus that gsettings needs, whereas plain cron jobs often can't.

~/.config/systemd/user/nexwall.service:

[Unit]
Description=NexWall daily wallpaper

[Service]
Type=oneshot
Environment=NEXWALL_API_KEY=YOUR_API_KEY
Environment=WALLPAPER_SIZE=1920x1080
ExecStart=/usr/bin/python3 %h/scripts/nexwall_daily.py

~/.config/systemd/user/nexwall.timer:

[Unit]
Description=Change wallpaper daily

[Timer]
OnCalendar=*-*-* 08:00:00
Persistent=true

[Install]
WantedBy=timers.target

systemctl --user daemon-reload
systemctl --user enable --now nexwall.timer

Persistent=true means that if your laptop was asleep at 08:00, the change happens the next time it wakes.

Ideas to extend it

Search instead of category: add params["search"] = "neon" (2 to 100 characters, matched against tags).
Multi-monitor: call fit_to_screen once per resolution and use your desktop's per-monitor setting.
"Popular this week" mode: use sort=popular with a small per_page and pick one item locally.
Quota awareness: every response includes X-RateLimit-Remaining. Log it if you share the key across scripts.

Is the free tier really enough?

For this use case, yes: one request a day against a limit of 100. The paid plans (Pro $4.99/mo with 10,000 requests/day and premium categories; Ultra $10.99/mo with live MP4 wallpapers) are aimed at apps with many users, not personal scripts.

Links: Docs · OpenAPI spec · Free key

Disclosure: I build NexWall. If the script misbehaves on your desktop environment, drop a comment with your distro/DE and I'll help, and update the post.

Build a 4K Wallpaper App in Flutter with a Free Wallpaper API (Step by Step)

Kodnex Technologies — Tue, 06 Oct 2026 05:56:48 +0000

Disclosure: I build NexWall, the wallpaper API used in this tutorial. Most of the Flutter code here (pagination, image caching, MethodChannels) works the same with any JSON image API, so you can swap the data source if you prefer something else.

Full source code: kodnextechnologies/nexwall-flutter-wallpaper-app (MIT licensed)

Wallpaper apps are a common first "real" Flutter project. You get networking, grids, caching, pagination and a bit of native platform code. The awkward part is usually the content: where do you get a legal, consistent supply of high-resolution portrait images without scraping anything?

In this tutorial we'll build a small but complete wallpaper app with:

A horizontal row of category chips
An infinite-scroll grid of thumbnails
A full-screen preview
A "Set as wallpaper" button on Android, using a tiny MethodChannel and Android's WallpaperManager

For content we'll use the NexWall wallpaper REST API. It's a free wallpaper API tier with 100 requests/day, 60 requests/minute, and no credit card. It serves vertical 9:16 wallpapers up to 2160x3840 across 50+ categories (the free tier covers the non-premium categories).

1. Get an API key

Register at https://nexwall.kodnextech.com/developers/register, verify your email, and copy the key. Every request sends it as a Bearer token:

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Quick sanity check from a terminal:

curl "https://nexwall.kodnextech.com/api/developer/v1/categories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

You should get back something like this:

{
  "data": [
    {
      "id": 1,
      "name": "AMOLED & Pure Black",
      "slug": "dark-moody",
      "cover_image_url": "https://nexwall.kodnextech.com/storage/categories/amoled.webp",
      "wallpaper_count": 248,
      "is_premium": false
    }
  ],
  "plan": "free",
  "remaining_requests_today": 99
}

Note remaining_requests_today. With 100 requests per day on the free tier, it's worth caching during development. More on that at the end.

2. Project setup

flutter create nexwall_demo
cd nexwall_demo
flutter pub add http cached_network_image

We won't hard-code the key. Instead we'll pass it at build time:

flutter run --dart-define=NEXWALL_API_KEY=YOUR_API_KEY

Important for production: a --dart-define value still ends up inside your APK/IPA, and anyone can extract it. That's fine for learning and prototypes. For a shipped app, put a small backend proxy in front of the API so the key stays on your server, and point baseUrl at your proxy instead. The NexWall docs recommend the same thing.

3. Models

The wallpaper feed (GET /wallpapers) returns a Laravel-style paginated payload: data, current_page, last_page, per_page, total, plus plan and remaining_requests_today. We only map the fields we use.

lib/models.dart:

class Category {
  final int id;
  final String name;
  final String? coverImageUrl;
  final int wallpaperCount;

  Category({
    required this.id,
    required this.name,
    this.coverImageUrl,
    required this.wallpaperCount,
  });

  factory Category.fromJson(Map<String, dynamic> json) => Category(
        id: json['id'] as int,
        name: json['name'] as String,
        coverImageUrl: json['cover_image_url'] as String?,
        wallpaperCount: (json['wallpaper_count'] ?? 0) as int,
      );
}

class Wallpaper {
  final int id;
  final String imageUrl;
  final String thumbnailUrl;
  final String? resolution;
  final String? tags;

  Wallpaper({
    required this.id,
    required this.imageUrl,
    required this.thumbnailUrl,
    this.resolution,
    this.tags,
  });

  factory Wallpaper.fromJson(Map<String, dynamic> json) => Wallpaper(
        id: json['id'] as int,
        imageUrl: json['image_url'] as String,
        // Fall back to the full image if a thumbnail is ever missing.
        thumbnailUrl: (json['thumbnail_url'] ?? json['image_url']) as String,
        resolution: json['resolution'] as String?,
        tags: json['tags'] as String?,
      );
}

class WallpaperPage {
  final List<Wallpaper> items;
  final int currentPage;
  final int lastPage;

  WallpaperPage({
    required this.items,
    required this.currentPage,
    required this.lastPage,
  });

  bool get hasMore => currentPage < lastPage;
}

4. A small API client

The API has four GET endpoints. We'll use two of them: /categories and /wallpapers (with optional category_id, page, per_page, and sort). We also handle the status codes the API documents: 401 for a bad key, 429 for rate limits (with a Retry-After header), and 422 for invalid query parameters.

lib/nexwall_api.dart:

import 'dart:convert';
import 'package:http/http.dart' as http;
import 'models.dart';

class NexWallException implements Exception {
  final String message;
  NexWallException(this.message);
  @override
  String toString() => message;
}

class NexWallApi {
  NexWallApi({
    required this.apiKey,
    this.baseUrl = 'https://nexwall.kodnextech.com/api/developer/v1',
    http.Client? client,
  }) : _client = client ?? http.Client();

  final String apiKey;
  final String baseUrl;
  final http.Client _client;

  Future<Map<String, dynamic>> _get(String path,
      [Map<String, String>? query]) async {
    final uri = Uri.parse('$baseUrl$path')
        .replace(queryParameters: (query == null || query.isEmpty) ? null : query);

    final res = await _client.get(uri, headers: {
      'Authorization': 'Bearer $apiKey',
      'Accept': 'application/json',
    });

    switch (res.statusCode) {
      case 200:
        return jsonDecode(res.body) as Map<String, dynamic>;
      case 401:
        throw NexWallException('Missing or invalid API key.');
      case 422:
        throw NexWallException('Invalid query parameters: ${res.body}');
      case 429:
        final retry = res.headers['retry-after'] ?? '?';
        throw NexWallException('Rate limit reached. Retry after $retry s.');
      default:
        throw NexWallException('Request failed (${res.statusCode}).');
    }
  }

  Future<List<Category>> categories() async {
    final json = await _get('/categories');
    return (json['data'] as List)
        .map((e) => Category.fromJson(e as Map<String, dynamic>))
        .toList();
  }

  Future<WallpaperPage> wallpapers({
    int page = 1,
    int perPage = 30,
    int? categoryId,
    String sort = 'newest', // newest | oldest | popular | random
  }) async {
    final json = await _get('/wallpapers', {
      'page': '$page',
      'per_page': '$perPage',
      'sort': sort,
      'type': 'image',
      if (categoryId != null) 'category_id': '$categoryId',
    });

    return WallpaperPage(
      items: (json['data'] as List)
          .map((e) => Wallpaper.fromJson(e as Map<String, dynamic>))
          .toList(),
      currentPage: json['current_page'] as int,
      lastPage: json['last_page'] as int,
    );
  }
}

per_page accepts 1 to 100. I use 30 so one request fills a couple of screens without using a large share of the daily quota on scrolling.

5. The home screen: chips + infinite grid

lib/main.dart:

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter/material.dart';
import 'models.dart';
import 'nexwall_api.dart';
import 'preview_screen.dart';

const apiKey = String.fromEnvironment('NEXWALL_API_KEY');

void main() {
  assert(apiKey.isNotEmpty, 'Pass --dart-define=NEXWALL_API_KEY=...');
  runApp(const WallpaperApp());
}

class WallpaperApp extends StatelessWidget {
  const WallpaperApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'NexWall Demo',
      theme: ThemeData.dark(useMaterial3: true),
      home: const HomeScreen(),
    );
  }
}

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});
  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  final api = NexWallApi(apiKey: apiKey);
  final scroll = ScrollController();

  List<Category> categories = [];
  int? selectedCategoryId;

  final List<Wallpaper> wallpapers = [];
  int page = 1;
  bool hasMore = true;
  bool loading = false;
  String? error;

  @override
  void initState() {
    super.initState();
    _loadCategories();
    _loadMore();
    scroll.addListener(() {
      if (scroll.position.pixels > scroll.position.maxScrollExtent - 600) {
        _loadMore();
      }
    });
  }

  Future<void> _loadCategories() async {
    try {
      final result = await api.categories();
      setState(() => categories = result);
    } catch (e) {
      setState(() => error = e.toString());
    }
  }

  Future<void> _loadMore() async {
    if (loading || !hasMore) return;
    setState(() => loading = true);
    try {
      final result = await api.wallpapers(
        page: page,
        categoryId: selectedCategoryId,
      );
      setState(() {
        wallpapers.addAll(result.items);
        hasMore = result.hasMore;
        page = result.currentPage + 1;
        error = null;
      });
    } catch (e) {
      setState(() => error = e.toString());
    } finally {
      setState(() => loading = false);
    }
  }

  void _selectCategory(int? id) {
    setState(() {
      selectedCategoryId = id;
      wallpapers.clear();
      page = 1;
      hasMore = true;
    });
    _loadMore();
  }

  @override
  void dispose() {
    scroll.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Wallpapers')),
      body: Column(
        children: [
          SizedBox(
            height: 56,
            child: ListView(
              scrollDirection: Axis.horizontal,
              padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
              children: [
                _chip('All', null),
                for (final c in categories) _chip(c.name, c.id),
              ],
            ),
          ),
          if (error != null)
            Padding(
              padding: const EdgeInsets.all(8),
              child: Text(error!, style: const TextStyle(color: Colors.redAccent)),
            ),
          Expanded(
            child: GridView.builder(
              controller: scroll,
              padding: const EdgeInsets.all(8),
              gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
                crossAxisCount: 3,
                mainAxisSpacing: 8,
                crossAxisSpacing: 8,
                childAspectRatio: 9 / 16, // portrait wallpapers
              ),
              itemCount: wallpapers.length + (loading ? 1 : 0),
              itemBuilder: (context, i) {
                if (i >= wallpapers.length) {
                  return const Center(child: CircularProgressIndicator());
                }
                final w = wallpapers[i];
                return GestureDetector(
                  onTap: () => Navigator.push(
                    context,
                    MaterialPageRoute(builder: (_) => PreviewScreen(wallpaper: w)),
                  ),
                  child: Hero(
                    tag: 'wp-${w.id}',
                    child: ClipRRect(
                      borderRadius: BorderRadius.circular(12),
                      child: CachedNetworkImage(
                        imageUrl: w.thumbnailUrl,
                        fit: BoxFit.cover,
                        placeholder: (_, __) => Container(color: Colors.white10),
                        errorWidget: (_, __, ___) => const Icon(Icons.broken_image),
                      ),
                    ),
                  ),
                );
              },
            ),
          ),
        ],
      ),
    );
  }

  Widget _chip(String label, int? id) => Padding(
        padding: const EdgeInsets.only(right: 8),
        child: ChoiceChip(
          label: Text(label),
          selected: selectedCategoryId == id,
          onSelected: (_) => _selectCategory(id),
        ),
      );
}

A few notes:

The grid uses thumbnail_url, not image_url. The full images go up to 2160x3840 and are far too heavy for a grid of 30 tiles.
childAspectRatio: 9 / 16 matches the portrait format, so nothing gets awkwardly cropped.
Images are served directly by URL. Loading an image file doesn't count as an API request; only the JSON endpoints do.

6. Full-screen preview

lib/preview_screen.dart:

import 'package:cached_network_image/cached_network_image.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:http/http.dart' as http;
import 'models.dart';

class PreviewScreen extends StatefulWidget {
  const PreviewScreen({super.key, required this.wallpaper});
  final Wallpaper wallpaper;

  @override
  State<PreviewScreen> createState() => _PreviewScreenState();
}

class _PreviewScreenState extends State<PreviewScreen> {
  static const channel = MethodChannel('nexwall/wallpaper');
  bool busy = false;

  // 1 = home screen, 2 = lock screen, 3 = both
  Future<void> _setWallpaper(int target) async {
    setState(() => busy = true);
    try {
      final res = await http.get(Uri.parse(widget.wallpaper.imageUrl));
      if (res.statusCode != 200) {
        throw Exception('Download failed (${res.statusCode})');
      }
      await channel.invokeMethod('setWallpaper', {
        'bytes': res.bodyBytes,
        'target': target,
      });
      if (mounted) {
        ScaffoldMessenger.of(context)
            .showSnackBar(const SnackBar(content: Text('Wallpaper set')));
      }
    } catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context)
            .showSnackBar(SnackBar(content: Text('Failed: $e')));
      }
    } finally {
      if (mounted) setState(() => busy = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    final w = widget.wallpaper;
    final isAndroid = !kIsWeb && defaultTargetPlatform == TargetPlatform.android;

    return Scaffold(
      backgroundColor: Colors.black,
      appBar: AppBar(
        backgroundColor: Colors.transparent,
        title: Text(w.resolution ?? ''),
      ),
      extendBodyBehindAppBar: true,
      body: Hero(
        tag: 'wp-${w.id}',
        child: CachedNetworkImage(
          imageUrl: w.imageUrl,
          fit: BoxFit.cover,
          width: double.infinity,
          height: double.infinity,
          placeholder: (_, __) => CachedNetworkImage(
            imageUrl: w.thumbnailUrl,
            fit: BoxFit.cover,
          ),
        ),
      ),
      floatingActionButton: isAndroid
          ? FloatingActionButton.extended(
              onPressed: busy ? null : () => _showTargets(context),
              icon: busy
                  ? const SizedBox(
                      width: 18, height: 18,
                      child: CircularProgressIndicator(strokeWidth: 2))
                  : const Icon(Icons.wallpaper),
              label: const Text('Set as wallpaper'),
            )
          : null,
    );
  }

  void _showTargets(BuildContext context) {
    showModalBottomSheet(
      context: context,
      builder: (_) => SafeArea(
        child: Column(mainAxisSize: MainAxisSize.min, children: [
          ListTile(title: const Text('Home screen'),
              onTap: () { Navigator.pop(context); _setWallpaper(1); }),
          ListTile(title: const Text('Lock screen'),
              onTap: () { Navigator.pop(context); _setWallpaper(2); }),
          ListTile(title: const Text('Both'),
              onTap: () { Navigator.pop(context); _setWallpaper(3); }),
        ]),
      ),
    );
  }
}

Using the thumbnail as the placeholder for the full image gives a nice "blur-up" effect for free, since the thumbnail is usually already in cache from the grid.

7. The Android side: a 30-line MethodChannel

There are pub.dev plugins for setting wallpapers, but the native code is small enough that I prefer owning it. Flutter's Uint8List arrives on the Kotlin side as a ByteArray.

android/app/src/main/kotlin/<your/package>/MainActivity.kt:

package com.example.nexwall_demo

import android.app.WallpaperManager
import android.os.Build
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel
import java.io.ByteArrayInputStream

class MainActivity : FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)

        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "nexwall/wallpaper")
            .setMethodCallHandler { call, result ->
                if (call.method != "setWallpaper") {
                    result.notImplemented()
                    return@setMethodCallHandler
                }
                val bytes = call.argument<ByteArray>("bytes")
                val target = call.argument<Int>("target") ?: 1
                if (bytes == null) {
                    result.error("NO_BYTES", "No image data received", null)
                    return@setMethodCallHandler
                }

                // WallpaperManager does disk + decode work: keep it off the UI thread.
                Thread {
                    try {
                        val wm = WallpaperManager.getInstance(applicationContext)
                        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
                            val flags = when (target) {
                                1 -> WallpaperManager.FLAG_SYSTEM
                                2 -> WallpaperManager.FLAG_LOCK
                                else -> WallpaperManager.FLAG_SYSTEM or WallpaperManager.FLAG_LOCK
                            }
                            wm.setStream(ByteArrayInputStream(bytes), null, true, flags)
                        } else {
                            wm.setStream(ByteArrayInputStream(bytes))
                        }
                        runOnUiThread { result.success(true) }
                    } catch (e: Exception) {
                        runOnUiThread { result.error("SET_FAILED", e.message, null) }
                    }
                }.start()
            }
    }
}

Add the permission to android/app/src/main/AndroidManifest.xml (it's a normal permission, so no runtime prompt). Also make sure INTERNET is in the main manifest. Flutter only adds it to the debug/profile manifests by default, which is a classic "works in debug, blank in release" bug:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.SET_WALLPAPER" />

Why setStream instead of decoding a Bitmap first? A 2160x3840 image is about 33 MB as an ARGB bitmap. Passing the stream lets the system handle decoding and avoids an easy out-of-memory crash on low-end devices.

iOS note: iOS has no public API for setting the wallpaper programmatically. The usual pattern is "Save to Photos", after which the user sets it from the Photos app. That's why the button above is Android-only.

8. Being nice to your quota

The free tier gives you 100 requests/day and 60/minute, which is plenty for building and testing if you avoid waste:

Cache categories. They rarely change. Fetch once per app launch, or store them for a day.
Use a sensible per_page. One request for 30 to 50 items is much better than many small ones.
Read the headers. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix timestamp; quotas reset at 00:00 UTC). On a 429, respect Retry-After.
Proxy + cache in production. A backend proxy keeps your key secret and lets many users share one cached response.

When you outgrow the free tier, Pro ($4.99/mo or ₹399/mo) raises the limit to 10,000 requests/day and unlocks all categories, including premium ones and commercial monetization rights. Ultra ($10.99/mo or ₹899/mo) adds looping MP4 live wallpapers via type=live. Read the Developer API License before shipping a monetized app.

Where to go next

Search: /wallpapers?search=neon matches tags (2 to 100 characters).
Discovery feed: sort=popular or sort=random makes a good "Explore" tab.
Auto-changer: schedule a daily sort=random&per_page=1 call with WorkManager and reuse the MethodChannel above.

Useful links:

Docs: https://nexwall.kodnextech.com/wallpaper-api/docs
OpenAPI spec: https://nexwall.kodnextech.com/openapi.json
In-browser sandbox: https://nexwall.kodnextech.com/wallpaper-api/sandbox
Free key: https://nexwall.kodnextech.com/developers/register

Once more for transparency: I work on NexWall. If something in the API is confusing or missing for your use case, tell me in the comments. That kind of feedback directly shapes what we build next.