Add stock images to a Next.js site with the Pix4Less API

# .env.local (never commit this file, never prefix the key with NEXT_PUBLIC_)
PIX4LESS_API_KEY=paste-your-key-here

{
  "query": "quiet coffee shop interior, morning light",
  "filters": {
    "orientation": "landscape"
  },
  "per_page": 6
}

curl https://pix4less.com/v1/images/search \
  -H "Authorization: Bearer $PIX4LESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"quiet coffee shop interior, morning light","filters":{"orientation":"landscape"},"per_page":6}'

// src/lib/pix4less.ts (server only: import it from Server Components and route handlers)
import "server-only";

const ORIGIN = "https://pix4less.com";
const TTL_MS = 60 * 60 * 1000;

type Rendition = { url: string; width: number; height: number };
type ApiImage = {
  id: string;
  title: string;
  description: string;
  renditions: { web?: Rendition; thumbnail?: Rendition };
  license: { code: string; url: string | null; status: string };
  content_warnings?: string[];
};

export type StockImageData = {
  id: string;
  src: string; // absolute preview URL on the Pix4Less origin
  width: number; // preview size, not the size of the original
  height: number;
  alt: string;
  title: string;
  license: { code: string; url: string | null };
};

export function apiKey(): string {
  const key = process.env.PIX4LESS_API_KEY;
  if (!key) throw new Error("PIX4LESS_API_KEY is not set");
  return key;
}

const cache = new Map<string, { expires: number; images: StockImageData[] }>();

export async function searchStockImages(query: string, perPage = 6): Promise<StockImageData[]> {
  const cacheKey = query.trim().toLowerCase() + "|" + perPage;
  const hit = cache.get(cacheKey);
  if (hit && hit.expires > Date.now()) return hit.images;

  const response = await fetch(ORIGIN + "/v1/images/search", {
    method: "POST",
    headers: { Authorization: "Bearer " + apiKey(), "Content-Type": "application/json" },
    body: JSON.stringify({ query, filters: { orientation: "landscape" }, per_page: perPage }),
    cache: "no-store",
  });
  if (!response.ok) {
    // Search is not idempotent: report the failure, do not retry automatically.
    const body = (await response.json().catch(() => null)) as { error?: { code?: string; request_id?: string } } | null;
    throw new Error("Pix4Less search failed: HTTP " + response.status + " " + (body?.error?.code ?? "") + " " + (body?.error?.request_id ?? ""));
  }

  const { data } = (await response.json()) as { data: ApiImage[] };
  const images = data.flatMap((image): StockImageData[] => {
    const preview = image.renditions.web ?? image.renditions.thumbnail;
    if (!preview) return [];
    return [{
      id: image.id,
      src: new URL(preview.url, ORIGIN).toString(), // the API returns a relative path
      width: preview.width,
      height: preview.height,
      alt: image.description,
      title: image.title,
      license: { code: image.license.code, url: image.license.url },
    }];
  });
  cache.set(cacheKey, { expires: Date.now() + TTL_MS, images });
  return images;
}

// src/app/stock/page.tsx
import Image from "next/image";
import { searchStockImages } from "@/lib/pix4less";

export default async function StockPage({ searchParams }: { searchParams: Promise<{ q?: string }> }) {
  const { q } = await searchParams;
  const query = q?.trim().slice(0, 200);
  // A search costs credits: only run it for a real query, on the server.
  // Every request with a new ?q= spends credits: put auth or a rate limit in front of this page.
  const images = query ? await searchStockImages(query) : [];

  return (
    <main>
      <form>
        <input name="q" defaultValue={query} placeholder="Describe the image you need" />
        <button type="submit">Search</button>
      </form>
      {query && images.length === 0 ? <p>No match. Try a broader description.</p> : null}
      <div>
        {images.map((image) => (
          <figure key={image.id}>
            {/* Previews are fixed-size files served as they are, so skip Next's optimizer. */}
            <Image
              unoptimized
              src={image.src}
              alt={image.alt}
              width={image.width}
              height={image.height}
              sizes="(max-width: 768px) 100vw, 33vw"
            />
            <figcaption>{image.title}</figcaption>
          </figure>
        ))}
      </div>
    </main>
  );
}

img-src 'self' https://pix4less.com

// src/app/api/stock-images/[id]/download/route.ts
import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { NextResponse } from "next/server";
import { apiKey } from "@/lib/pix4less";

const ORIGIN = "https://pix4less.com";
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const EXTENSIONS: Record<string, string> = { "image/jpeg": "jpg", "image/png": "png", "image/webp": "webp", "image/avif": "avif" };

// Every call can spend credits: put your own authentication in front of this route.
export async function POST(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  if (!UUID.test(id)) return NextResponse.json({ error: "Invalid image id" }, { status: 400 });

  // 1. Ask Pix4Less to authorize the original. A new image is charged once per account.
  const grant = await fetch(ORIGIN + "/v1/images/" + id + "/download", {
    method: "POST",
    headers: { Authorization: "Bearer " + apiKey() },
    cache: "no-store",
  });
  if (!grant.ok) return NextResponse.json({ error: "Download not authorized" }, { status: grant.status === 402 ? 402 : 502 });
  const { data } = (await grant.json()) as { data: { url: string; expires_at: string | null; owned: true } };

  // 2. Fetch the bytes right away, WITHOUT the API key. The signed URL is short-lived: do not log or store it.
  const file = await fetch(data.url, { cache: "no-store" });
  if (!file.ok) return NextResponse.json({ error: "Original could not be fetched" }, { status: 502 });
  const extension = EXTENSIONS[(file.headers.get("content-type") ?? "").split(";")[0]] ?? "bin";

  // 3. Keep the file yourself. Local disk keeps the example small; use your own object storage and CDN in production.
  const directory = join(process.cwd(), "stock-originals");
  await mkdir(directory, { recursive: true });
  const name = id + "." + extension;
  await writeFile(join(directory, name), Buffer.from(await file.arrayBuffer()));
  return NextResponse.json({ id, saved: name });
}