Pustaka Image Contribution API

Help us illustrate 10,000+ fairytale stories! Upload covers, character portraits, location backgrounds, and sprites. Use any model or draw by hand.

API Base URL

https://pustaka.org/api/cover-queue

Endpoints

Image Types

Quick Start

1. Find stories that need images

# Get 5 stories needing covers
curl https://pustaka.org/api/cover-queue/jobs?limit=5&status=pending

# Get full details for a specific story (all prompts)
curl https://pustaka.org/api/cover-queue/lookup/english/grimm/household_tales/snow_white

2. Upload an image

# Upload a cover (by job index)
curl -X POST https://pustaka.org/api/cover-queue/submit/42 \
  -F "image=@cover.png"

# Upload a character (by story path)
curl -X POST https://pustaka.org/api/cover-queue/upload/english/grimm/household_tales/snow_white \
  -F "image=@snow_white.png" \
  -F "category=characters" \
  -F "name=Snow White"

# Upload a location
curl -X POST https://pustaka.org/api/cover-queue/upload/english/grimm/household_tales/snow_white \
  -F "image=@cottage.png" \
  -F "category=locations" \
  -F "name=Dwarfs Cottage"

# Upload a sprite
curl -X POST https://pustaka.org/api/cover-queue/upload/english/grimm/household_tales/snow_white \
  -F "image=@sprite.png" \
  -F "category=sprites"

Upload Fields

Sample Python Worker

#!/usr/bin/env python3
"""Fetch prompts and upload generated images."""
import requests

BASE = "https://pustaka.org/api/cover-queue"

# Get stories needing covers
jobs = requests.get(f"{BASE}/jobs", params={"limit": 5, "status": "pending"}).json()["jobs"]

for job in jobs:
    print(f"[{job['index']}] {job['story_path']}")
    print(f"  Prompt: {job['prompt'][:100]}...")

    # TODO: Generate image with your model
    # img_bytes = generate(job["prompt"])

    # Upload cover
    # requests.post(f"{BASE}/submit/{job['index']}",
    #     files={"image": ("cover.png", img_bytes, "image/png")},
    #     data={"worker": "my-bot", "provider": "my-model"})

# Get all prompts for a specific story
story = requests.get(f"{BASE}/lookup/english/grimm/household_tales/snow_white").json()

# Upload character images
for char in story["assets"]["characters"]:
    print(f"Character: {char['name']}")
    print(f"  Prompt: {char['prompt'][:100]}...")

    # TODO: Generate character image
    # img_bytes = generate(char["prompt"])

    # Upload character
    # requests.post(f"{BASE}/upload/{story['story_path']}",
    #     files={"image": (f"{char['name']}.png", img_bytes, "image/png")},
    #     data={"category": "characters", "name": char["name"]})

Response Examples

GET /lookup/:storyPath

{
  "story_path": "english/grimm/household_tales/snow_white",
  "assets": {
    "cover": 1,
    "characters": [
      { "name": "Snow-white", "prompt": "A young woman with skin as white as snow...", "images": 0 },
      { "name": "The Queen", "prompt": "A tall, slender woman in her late 40s...", "images": 0 }
    ],
    "locations": [
      { "name": "Dwarfs' Cottage", "prompt": "A cozy, tiny stone cottage...", "images": 0 }
    ],
    "sprites": 0
  },
  "cover_index": 80,
  "cover_prompt": "Seven-year-old Snow-white stands frozen in fear...",
  "cover_status": "done"
}

POST /upload/:storyPath

{ "success": true, "story_path": "...", "category": "characters", "filename": "snow_white.png", "total": 1 }

POST /submit/:index

{ "success": true, "story_path": "...", "filename": "cover.png", "is_alternative": false, "total_covers": 1 }

Errors

Pustaka Fairytale Library — pustaka.org