Hourlore HTTP API: documentary previews and renders

Get an API key

Sign in with your email link and create a key under Account → API keys. The plaintext key is shown once. Keep it private—anyone holding it can spend credits on your account—and revoke it anytime if needed.

POST /api/v1/previews

Research a topic on Wikipedia and generate an 8–12 shot opening storyboard with narration script, Creative Commons archive images, maps and number cards (~25s). Free, counted toward your daily account limit (15/day).

curl -X POST https://hourlore.com/api/v1/previews \
  -H "Authorization: Bearer $HOURLORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "The night Krakatoa exploded",
    "notes": "Focus on global acoustic shockwaves and weather aftermath"
  }'

Response:

{
  "title": "The Night Krakatoa Heard Around the World",
  "topic": "The night Krakatoa exploded",
  "wikiTitles": ["1883 eruption of Krakatoa"],
  "shots": [
    {
      "kind": "map",
      "narration": "In August 1883, a volcanic island between Java and Sumatra tore itself apart.",
      "label": "Sunda Strait, 1883",
      "lat": -6.102,
      "lon": 105.423,
      "rings": true
    },
    {
      "kind": "number",
      "narration": "The third blast registered 3,000 miles away on Rodrigues Island.",
      "value": "3,000 miles",
      "label": "Audible radius",
      "countUp": true
    }
  ]
}

POST /api/v1/films

Queue a full 1080p (16:9) narrated MP4 documentary render. Pick 5 minutes (25 credits), 10 minutes (50 credits) or 15 minutes (75 credits), and narrator voice "olivia" (female) or "owen" (male). Pass an optional Idempotency-Key header so safe retries return the same job.

curl -X POST https://hourlore.com/api/v1/films \
  -H "Authorization: Bearer $HOURLORE_API_KEY" \
  -H "Idempotency-Key: krakatoa-ep01" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "The night Krakatoa exploded",
    "minutes": 10,
    "voice": "owen",
    "notes": "Focus on acoustic shockwaves and sunset optical effects"
  }'

Response:

{
  "id": "V9x2Qp7Lm4Kc",
  "status": "queued",
  "topic": "The night Krakatoa exploded",
  "notes": "Focus on acoustic shockwaves and sunset optical effects",
  "minutes": 10,
  "voice": "owen",
  "credits": 50,
  "cancelable": true,
  "attempts": 0,
  "stage": null,
  "title": null,
  "description_text": null,
  "error": null,
  "download_url": null,
  "download_url_expires_at": null,
  "created_at": "2026-11-15T08:00:00.000Z",
  "updated_at": "2026-11-15T08:00:00.000Z"
}

GET /api/v1/films/:id

Poll render progress (status is queued, rendering, completed or failed). Once completed, download_url contains a 1-hour signed MP4 URL and description_text contains Creative Commons image attributions.

curl https://hourlore.com/api/v1/films/V9x2Qp7Lm4Kc \
  -H "Authorization: Bearer $HOURLORE_API_KEY"

Response:

{
  "id": "V9x2Qp7Lm4Kc",
  "status": "completed",
  "topic": "The night Krakatoa exploded",
  "notes": "Focus on acoustic shockwaves and sunset optical effects",
  "minutes": 10,
  "voice": "owen",
  "credits": 50,
  "cancelable": false,
  "attempts": 1,
  "stage": "completed",
  "title": "The Sound That Circled Earth Four Times",
  "description_text": "Image credits (Wikimedia Commons): ...",
  "error": null,
  "download_url": "https://...",
  "download_url_expires_at": "2026-11-15T09:20:00.000Z",
  "created_at": "2026-11-15T08:00:00.000Z",
  "updated_at": "2026-11-15T08:18:42.000Z"
}

DELETE /api/v1/films/:id

Cancel a queued documentary before rendering starts and immediately release held credits back to your account.

curl -X DELETE https://hourlore.com/api/v1/films/V9x2Qp7Lm4Kc \
  -H "Authorization: Bearer $HOURLORE_API_KEY"

Response:

{
  "id": "V9x2Qp7Lm4Kc",
  "status": "failed",
  "credits": 50,
  "cancelable": false,
  "error": "Canceled by user"
}

GET /api/v1/credits

Read available and held credits on the account. Does not spend credits.

curl https://hourlore.com/api/v1/credits \
  -H "Authorization: Bearer $HOURLORE_API_KEY"

Response:

{ "credits": 150, "held": 0, "credits_per_minute": 5 }

Errors

Credits and limits

• API keys share the credit balance on your Hourlore account (5 credits per finished minute: 25 for 5 min, 50 for 10 min, 75 for 15 min).
• Credits are held when a film is queued, settled when the MP4 finishes, and returned automatically if canceled or failed.
• Free storyboard previews via POST /api/v1/previews count toward your account limit (15/day).
• Finished MP4 files remain available for 7 days; each signed download_url expires after 1 hour (re-fetch GET /api/v1/films/:id for a fresh URL).
• Rate limit: 120 requests per minute per API key.