Overview

The public image API gives read-only access to images that have already been generated and saved in Visibible.

• Base URL: https://www.visibible.com/api/public/images
• Auth: none
• Access: public, read-only
• CORS: enabled for GET and OPTIONS
• Format: JSON

Endpoints

API index

GET /api/public/images

Returns the API version, capability summary, and route templates.

Books with images

GET /api/public/images/books

Returns books that currently have at least one saved image.

Chapters with images for a book

GET /api/public/images/books/{book}/chapters

Returns chapter numbers that currently have at least one saved image.

Latest images in a chapter

GET /api/public/images/chapters/{book}/{chapter}

Returns the latest saved image for each verse in a chapter that currently has art.

Latest image for a verse

GET /api/public/images/verses/{book}/{chapter}/{verse}

Returns the latest saved image for one verse.

Paginated image history for a verse

GET /api/public/images/verses/{book}/{chapter}/{verse}/images?limit=20&cursor=...

Returns a paginated list of saved images for one verse.

Example requests

curl "https://www.visibible.com/api/public/images"
curl "https://www.visibible.com/api/public/images/books"
curl "https://www.visibible.com/api/public/images/books/genesis/chapters"
curl "https://www.visibible.com/api/public/images/chapters/genesis/1"
curl "https://www.visibible.com/api/public/images/verses/john/3/16"
curl "https://www.visibible.com/api/public/images/verses/genesis/1/1/images?limit=10"

Example verse response

{
  "data": {
    "verse": {
      "book": "genesis",
      "bookName": "Genesis",
      "chapter": 1,
      "verse": 1,
      "reference": "Genesis 1:1",
      "pageUrl": "https://visibible.com/genesis/1/1",
      "historyUrl": "https://www.visibible.com/api/public/images/verses/genesis/1/1/images"
    },
    "image": {
      "id": "abc123",
      "imageUrl": "https://actions.visibible.com/image/storage_id",
      "reference": "Genesis 1:1",
      "pageUrl": "https://visibible.com/genesis/1/1",
      "model": "google/gemini-2.5-flash-image",
      "translationId": "web",
      "aspectRatio": "16:9",
      "imageMimeType": "image/png",
      "imageWidth": 1024,
      "imageHeight": 768,
      "createdAt": 1742580000000
    }
  }
}

Pagination

Verse history uses cursor pagination.

• Default limit: 20
• Max limit: 50
• Invalid limit values return 400
• cursor must be the opaque token from a previous response
• Response includes:
  • pageInfo.nextCursor
  • pageInfo.hasMore

Example paginated history response

{
  "data": {
    "verse": {
      "book": "genesis",
      "bookName": "Genesis",
      "chapter": 1,
      "verse": 1,
      "reference": "Genesis 1:1",
      "pageUrl": "https://visibible.com/genesis/1/1",
      "historyUrl": "https://www.visibible.com/api/public/images/verses/genesis/1/1/images"
    },
    "image": {
      "id": "abc123",
      "imageUrl": "https://actions.visibible.com/image/storage_id",
      "reference": "Genesis 1:1",
      "pageUrl": "https://visibible.com/genesis/1/1",
      "model": "google/gemini-2.5-flash-image",
      "translationId": "web",
      "aspectRatio": "16:9",
      "imageMimeType": "image/png",
      "imageWidth": 1024,
      "imageHeight": 768,
      "createdAt": 1742580000000
    },
    "images": [
      {
        "id": "abc123",
        "imageUrl": "https://actions.visibible.com/image/storage_id",
        "reference": "Genesis 1:1",
        "pageUrl": "https://visibible.com/genesis/1/1",
        "model": "google/gemini-2.5-flash-image",
        "translationId": "web",
        "aspectRatio": "16:9",
        "imageMimeType": "image/png",
        "imageWidth": 1024,
        "imageHeight": 768,
        "createdAt": 1742580000000
      }
    ],
    "pageInfo": {
      "nextCursor": "opaque_cursor_token",
      "hasMore": true
    }
  }
}

Rate limits

Public requests are rate limited by IP address.

• Discovery endpoints: 120/minute
• Verse latest: 60/minute
• Verse history: 30/minute
• Chapter latest-per-verse: 20/minute

Rate-limited requests return 429 and include a Retry-After header.

Errors

Errors use this envelope:

{
  "error": "Bad request",
  "message": "Invalid query parameters."
}

Common status codes:

• 400 Bad request: Returned when a query parameter is invalid, such as a non-numeric or out-of-range limit.
• 404 Not found: Returned when the requested book/chapter/verse is unknown, or when a verse has no saved image yet.
• 429 Rate limit exceeded: Returned when an IP exceeds the endpoint's anonymous request budget. Responses include Retry-After.
• 503 Service unavailable: Returned when the public API backend is not currently wired to Convex or is temporarily unavailable.
• 500 Internal server error: Returned for unexpected server-side failures while serving the request.

Public fields only

Public responses intentionally exclude internal generation details like:

• prompts
• prompt inputs
• cost data
• provider request IDs
• session data
• analytics fields