CMS & blog auto-illustrator

const base = process.env.EPOCHAL_API_BASE ?? "https://epochalstock.com/api/v1";
const apiKey = process.env.EPOCHAL_API_KEY;
if (!apiKey) throw new Error("Set EPOCHAL_API_KEY on the CMS server");

const STOP = new Set(["the", "a", "an", "and", "or", "to", "of", "in", "on", "for", "with"]);

/** Derive q/tags from CMS post fields — runs only on your backend */
function buildHints({ title = "", bodyHtml = "", cmsTags = [] }) {
  let q = String(title).replace(/\s+/g, " ").trim();
  if (q.length < 12) {
    const text = String(bodyHtml).replace(/<[^>]+>/g, " ");
    const tokens = text
      .toLowerCase()
      .split(/[^a-z0-9]+/i)
      .filter((t) => t.length > 3 && !STOP.has(t));
    q = [...new Set(tokens)].slice(0, 8).join(" ");
  }
  q = q.slice(0, 200);
  const tags = [...new Set(cmsTags.map((t) => String(t).toLowerCase().trim()).filter(Boolean))].slice(0, 20);
  return {
    q,
    tags: tags.join(","),
    tag_mode: tags.length > 1 ? "any" : "all",
    sort: q ? "relevance" : "newest",
    limit: "24",
  };
}

async function suggestForPost(post, { cursor } = {}) {
  const hints = buildHints(post);
  const params = new URLSearchParams({
    sort: hints.sort,
    limit: hints.limit,
  });
  if (hints.q) params.set("q", hints.q);
  if (hints.tags) {
    params.set("tags", hints.tags);
    params.set("tag_mode", hints.tag_mode);
  }
  if (cursor) params.set("cursor", cursor);

  const res = await fetch(`${base}/images?${params}`, {
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  });
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") || "2");
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return suggestForPost(post, { cursor });
  }
  if (!res.ok) throw new Error(await res.text());
  const { data, meta } = await res.json();
  return {
    images: data.images,
    total: data.total,
    nextCursor: data.next_cursor ?? null,
    filters: data.filters,
    requestId: meta?.request_id,
    hints,
  };
}

// Example: CMS route handler receives session-authenticated editor + post id
// const result = await suggestForPost({ title, bodyHtml, cmsTags });

<?php
declare(strict_types=1);

$base = rtrim(getenv('EPOCHAL_API_BASE') ?: 'https://epochalstock.com/api/v1', '/');
$apiKey = getenv('EPOCHAL_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set EPOCHAL_API_KEY on the CMS server');
}

/**
 * @param array{title?:string,body_html?:string,cms_tags?:list<string>} $post
 * @return array{q:string,tags:string,tag_mode:string,sort:string,limit:int}
 */
function build_hints(array $post): array
{
    $stop = ['the','a','an','and','or','to','of','in','on','for','with'];
    $q = trim(preg_replace('/\s+/', ' ', (string) ($post['title'] ?? '')) ?? '');
    if (strlen($q) < 12) {
        $text = strip_tags((string) ($post['body_html'] ?? ''));
        $parts = preg_split('/[^a-z0-9]+/i', strtolower($text)) ?: [];
        $tokens = [];
        foreach ($parts as $t) {
            if (strlen($t) > 3 && !in_array($t, $stop, true)) {
                $tokens[$t] = true;
            }
        }
        $q = implode(' ', array_slice(array_keys($tokens), 0, 8));
    }
    $q = substr($q, 0, 200);
    $tags = [];
    foreach ($post['cms_tags'] ?? [] as $t) {
        $n = strtolower(trim((string) $t));
        if ($n !== '') {
            $tags[$n] = true;
        }
    }
    $tagList = array_slice(array_keys($tags), 0, 20);

    return [
        'q' => $q,
        'tags' => implode(',', $tagList),
        'tag_mode' => count($tagList) > 1 ? 'any' : 'all',
        'sort' => $q !== '' ? 'relevance' : 'newest',
        'limit' => 24,
    ];
}

/**
 * @return array<string,mixed>
 */
function suggest_for_post(string $base, string $apiKey, array $post, ?string $cursor = null): array
{
    $hints = build_hints($post);
    $params = [
        'sort' => $hints['sort'],
        'limit' => $hints['limit'],
    ];
    if ($hints['q'] !== '') {
        $params['q'] = $hints['q'];
    }
    if ($hints['tags'] !== '') {
        $params['tags'] = $hints['tags'];
        $params['tag_mode'] = $hints['tag_mode'];
    }
    if ($cursor) {
        $params['cursor'] = $cursor;
    }

    $ch = curl_init($base . '/images?' . http_build_query($params));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 429) {
        sleep(2);
        return suggest_for_post($base, $apiKey, $post, $cursor);
    }
    if ($status !== 200) {
        throw new RuntimeException((string) $raw);
    }
    $payload = json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR);
    return [
        'hints' => $hints,
        'data' => $payload['data'],
        'request_id' => $payload['meta']['request_id'] ?? null,
    ];
}

// $result = suggest_for_post($base, $apiKey, [
//     'title' => 'Remote work desk setups that actually focus',
//     'body_html' => '<p>Monitors, lighting, ergonomic chairs…</p>',
//     'cms_tags' => ['office', 'technology'],
// ]);
// Persist nothing yet — return $result['data']['images'] to the authenticated editor UI.

import os
import re
import time
from typing import Any

import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")
api_key = os.environ["EPOCHAL_API_KEY"]
STOP = {"the", "a", "an", "and", "or", "to", "of", "in", "on", "for", "with"}


def build_hints(title: str = "", body_html: str = "", cms_tags: list[str] | None = None) -> dict[str, Any]:
    q = re.sub(r"\s+", " ", title or "").strip()
    if len(q) < 12:
        text = re.sub(r"<[^>]+>", " ", body_html or "")
        tokens = [
            t for t in re.split(r"[^a-z0-9]+", text.lower())
            if len(t) > 3 and t not in STOP
        ]
        # preserve order, unique
        seen: dict[str, None] = {}
        for t in tokens:
            seen.setdefault(t, None)
        q = " ".join(list(seen.keys())[:8])
    q = q[:200]
    tags = []
    for t in cms_tags or []:
        n = t.strip().lower()
        if n and n not in tags:
            tags.append(n)
    tags = tags[:20]
    return {
        "q": q,
        "tags": ",".join(tags),
        "tag_mode": "any" if len(tags) > 1 else "all",
        "sort": "relevance" if q else "newest",
        "limit": 24,
    }


def suggest_for_post(post: dict, cursor: str | None = None) -> dict:
    hints = build_hints(
        title=post.get("title", ""),
        body_html=post.get("body_html", ""),
        cms_tags=post.get("cms_tags"),
    )
    params: dict[str, Any] = {"sort": hints["sort"], "limit": hints["limit"]}
    if hints["q"]:
        params["q"] = hints["q"]
    if hints["tags"]:
        params["tags"] = hints["tags"]
        params["tag_mode"] = hints["tag_mode"]
    if cursor:
        params["cursor"] = cursor

    r = requests.get(
        f"{base}/images",
        params=params,
        headers={"Authorization": f"Bearer {api_key}", "Accept": "application/json"},
        timeout=20,
    )
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "2")))
        return suggest_for_post(post, cursor)
    r.raise_for_status()
    body = r.json()
    return {"hints": hints, "data": body["data"], "request_id": body.get("meta", {}).get("request_id")}

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "regexp"
    "strings"
    "time"
)

var nonWord = regexp.MustCompile(`[^a-z0-9]+`)

func buildHints(title, bodyHTML string, cmsTags []string) url.Values {
    q := strings.Join(strings.Fields(title), " ")
    if len(q) < 12 {
        text := regexp.MustCompile(`<[^>]+>`).ReplaceAllString(bodyHTML, " ")
        parts := nonWord.Split(strings.ToLower(text), -1)
        stop := map[string]bool{"the": true, "a": true, "an": true, "and": true, "or": true, "to": true, "of": true, "in": true, "on": true, "for": true, "with": true}
        var tokens []string
        seen := map[string]bool{}
        for _, t := range parts {
            if len(t) > 3 && !stop[t] && !seen[t] {
                seen[t] = true
                tokens = append(tokens, t)
                if len(tokens) == 8 {
                    break
                }
            }
        }
        q = strings.Join(tokens, " ")
    }
    if len(q) > 200 {
        q = q[:200]
    }
    tags := []string{}
    tseen := map[string]bool{}
    for _, t := range cmsTags {
        n := strings.ToLower(strings.TrimSpace(t))
        if n != "" && !tseen[n] {
            tseen[n] = true
            tags = append(tags, n)
            if len(tags) == 20 {
                break
            }
        }
    }
    v := url.Values{}
    if q != "" {
        v.Set("q", q)
        v.Set("sort", "relevance")
    } else {
        v.Set("sort", "newest")
    }
    if len(tags) > 0 {
        v.Set("tags", strings.Join(tags, ","))
        if len(tags) > 1 {
            v.Set("tag_mode", "any")
        } else {
            v.Set("tag_mode", "all")
        }
    }
    v.Set("limit", "24")
    return v
}

func suggest(base, apiKey string, q url.Values) (map[string]any, error) {
    req, _ := http.NewRequest(http.MethodGet, strings.TrimRight(base, "/")+"/images?"+q.Encode(), nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Accept", "application/json")
    client := &http.Client{Timeout: 20 * time.Second}
    res, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()
    b, _ := io.ReadAll(res.Body)
    if res.StatusCode == 429 {
        time.Sleep(2 * time.Second)
        return suggest(base, apiKey, q)
    }
    if res.StatusCode != 200 {
        return nil, fmt.Errorf("search %d: %s", res.StatusCode, b)
    }
    var payload map[string]any
    if err := json.Unmarshal(b, &payload); err != nil {
        return nil, err
    }
    return payload, nil
}

func main() {
    base := os.Getenv("EPOCHAL_API_BASE")
    if base == "" {
        base = "https://epochalstock.com/api/v1"
    }
    apiKey := os.Getenv("EPOCHAL_API_KEY")
    q := buildHints("Remote work desk setups", "<p>Monitors and lighting</p>", []string{"office", "technology"})
    // payload, err := suggest(base, apiKey, q)
    _, _ = base, apiKey
    _ = q
}

<?php
function fetch_image(string $base, string $apiKey, string $imageId): array
{
    $ch = curl_init(rtrim($base, '/') . '/images/' . rawurlencode($imageId));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        throw new RuntimeException((string) $raw);
    }
    return json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data'];
}

// attach_hero($pdo, $postId, $imageId): UPDATE posts SET hero_image_id = ? …

import os
import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")


def fetch_image(image_id: str) -> dict:
    r = requests.get(
        f"{base}/images/{image_id}",
        headers={
            "Authorization": f"Bearer {os.environ['EPOCHAL_API_KEY']}",
            "Accept": "application/json",
        },
        timeout=20,
    )
    r.raise_for_status()
    return r.json()["data"]


def attach_hero(db, post_id: int, image_id: str) -> dict:
    meta = fetch_image(image_id)
    db.execute(
        "UPDATE posts SET hero_image_id=%s, hero_title=%s WHERE id=%s",
        (meta["id"], meta["title"], post_id),
    )
    return meta

curl -sS "https://epochalstock.com/api/v1/images/es_001_example" \
  -H "Authorization: Bearer $EPOCHAL_API_KEY" \
  -H "Accept: application/json"
# Then UPDATE your posts table with data.id — there is no Epochal "attach" endpoint.

const base = process.env.EPOCHAL_API_BASE ?? "https://epochalstock.com/api/v1";

async function batchOnce(ids) {
  const res = await fetch(`${base}/images/batch`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.EPOCHAL_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ ids }),
  });
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") || "2");
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return batchOnce(ids);
  }
  if (!res.ok) throw new Error(await res.text());
  return (await res.json()).data;
}

/** Rehydrate hero cards for a page of posts (chunk at 100) */
async function hydrateHeroes(imageIds) {
  const unique = [...new Set(imageIds.filter(Boolean))];
  const images = [];
  for (let i = 0; i < unique.length; i += 100) {
    const data = await batchOnce(unique.slice(i, i + 100));
    images.push(...data.images);
  }
  return new Map(images.map((img) => [img.id, img]));
}

<?php
function batch_once(string $base, string $apiKey, array $ids): array
{
    $ch = curl_init(rtrim($base, '/') . '/images/batch');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['ids' => array_values($ids)], JSON_THROW_ON_ERROR),
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status === 429) {
        sleep(2);
        return batch_once($base, $apiKey, $ids);
    }
    if ($status !== 200) {
        throw new RuntimeException((string) $raw);
    }
    return json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data'];
}

function hydrate_heroes(string $base, string $apiKey, array $imageIds): array
{
    $unique = array_values(array_unique(array_filter($imageIds)));
    $byId = [];
    foreach (array_chunk($unique, 100) as $chunk) {
        $data = batch_once($base, $apiKey, $chunk);
        foreach ($data['images'] as $img) {
            $byId[$img['id']] = $img;
        }
    }
    return $byId;
}

import os
import time
import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")


def batch_once(ids: list[str]) -> dict:
    r = requests.post(
        f"{base}/images/batch",
        json={"ids": ids},
        headers={
            "Authorization": f"Bearer {os.environ['EPOCHAL_API_KEY']}",
            "Accept": "application/json",
        },
        timeout=20,
    )
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "2")))
        return batch_once(ids)
    r.raise_for_status()
    return r.json()["data"]


def hydrate_heroes(image_ids: list[str]) -> dict[str, dict]:
    unique = list(dict.fromkeys([i for i in image_ids if i]))
    out: dict[str, dict] = {}
    for i in range(0, len(unique), 100):
        data = batch_once(unique[i : i + 100])
        for img in data["images"]:
            out[img["id"]] = img
    return out

<?php
function export_original(string $base, string $apiKey, string $imageId, string $destPath, int $attempt = 1): void
{
    $ch = curl_init(rtrim($base, '/') . '/downloads');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
            'Accept: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode(['image_id' => $imageId], JSON_THROW_ON_ERROR),
        CURLOPT_TIMEOUT => 20,
    ]);
    $raw = curl_exec($ch);
    $status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 409) {
        if ($attempt >= 8) {
            throw new RuntimeException('lease busy too long');
        }
        usleep((int) ((500 * (2 ** ($attempt - 1))) + random_int(0, 250)) * 1000);
        export_original($base, $apiKey, $imageId, $destPath, $attempt + 1);
        return;
    }
    if ($status === 429) {
        sleep(5);
        export_original($base, $apiKey, $imageId, $destPath, $attempt + 1);
        return;
    }
    if ($status !== 201) {
        throw new RuntimeException('mint failed: ' . (string) $raw);
    }

    $url = json_decode((string) $raw, true, 512, JSON_THROW_ON_ERROR)['data']['download_url'];
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_TIMEOUT => 120,
    ]);
    $bytes = curl_exec($ch);
    $dl = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($dl !== 200) {
        throw new RuntimeException('download failed: ' . $dl);
    }
    file_put_contents($destPath, $bytes);
}

import os
import random
import time
import requests

base = os.environ.get("EPOCHAL_API_BASE", "https://epochalstock.com/api/v1").rstrip("/")
api_key = os.environ["EPOCHAL_API_KEY"]


def export_original(image_id: str, dest_path: str, attempt: int = 1) -> None:
    mint = requests.post(
        f"{base}/downloads",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
        json={"image_id": image_id},
        timeout=20,
    )
    if mint.status_code == 409:
        if attempt >= 8:
            raise RuntimeError("lease busy too long")
        time.sleep(min(30, 0.5 * (2 ** (attempt - 1))) + random.random() * 0.25)
        return export_original(image_id, dest_path, attempt + 1)
    if mint.status_code == 429:
        time.sleep(int(mint.headers.get("Retry-After", "5")))
        return export_original(image_id, dest_path, attempt + 1)
    mint.raise_for_status()
    url = mint.json()["data"]["download_url"]
    with requests.get(url, stream=True, timeout=120) as r:
        r.raise_for_status()
        with open(dest_path, "wb") as f:
            for chunk in r.iter_content(256 * 1024):
                if chunk:
                    f.write(chunk)

# Mint (Bearer required)
curl -sS -X POST "https://epochalstock.com/api/v1/downloads" \
  -H "Authorization: Bearer $EPOCHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"es_001_example"}'
# Then GET data.download_url with NO API key; save to private storage for OG processing.