Based on Us Connector API

A small, public API for starting a Based on Us comic on someone’s behalf — for AI assistants and other agentic platforms.

Overview

Based on Us turns a person’s photos and story into a personalized comic book, delivered as a private share link and a printable high-res PDF. The Connector API lets an AI assistant start a comic on someone’s behalf: it reads the catalog, creates a draft from what the person described, and returns a link where the person adds photos, sees a free preview with their real faces, and pays.

• Base URL: https://api.basedonus.com/connector/v1
• OpenAPI spec: https://api.basedonus.com/connector/v1/openapi.json
• No API key required.
• JSON over HTTPS.

How the handoff works

1. Call GET /catalog to read the current occasions, styles, tones and length tiers.
2. Call POST /comics with the story and choices the person gave you.
3. Give the person the returned continue_url.
4. They open it on basedonus.com, add photos (up to 4 characters, up to 3 photos each), see the free preview, and buy.
5. Optionally poll GET /comics/{comic_id} for the stage.

This is a handoff, not an end-to-end integration, for three reasons. Photos go directly from the person’s browser to Based on Us and never pass through the assistant. The API cannot trigger image generation or take payment — those stay gated behind the person’s own browser session once they open continue_url. And that URL carries a token that stays valid until the person starts adding photos — at that point the draft locks to whichever browser (or account) they used — so treat it as private to the person it was made for the whole time: don’t log it, cache it, or show it to anyone else.

Before the person opens continue_url, the draft’s content isn’t readable through any public endpoint — polling GET /comics/{comic_id} only ever returns the stage and price, never story text, photos, or anything else private. Once they open it, the draft follows the same rules as any comic started directly on basedonus.com: readable and editable only from the browser (or account) it’s bound to. Treat comic_id as private to the conversation it came from either way.

Endpoints

GET /catalog

Occasions, the visible art styles, tones, and length tiers with prices and limits. No request body or parameters. Validate every id from a draft against this before calling POST /comics — an unknown or hidden style is rejected.

curl https://api.basedonus.com/connector/v1/catalog

{
  "occasions": [
    {
      "id": "birthday",
      "label": "Birthday",
      "description": "Make their day legendary"
    },
    {
      "id": "couple",
      "label": "Couple / Anniversary",
      "description": "Your love story, illustrated"
    }
  ],
  "styles": [
    {
      "id": "superhero-comic",
      "label": "Superhero Comic"
    },
    {
      "id": "cute-storybook",
      "label": "Cute Storybook"
    }
  ],
  "tones": [
    {
      "id": "sweet",
      "label": "Sweet"
    },
    {
      "id": "funny",
      "label": "Funny"
    }
  ],
  "lengths": [
    {
      "id": "12",
      "label": "Short",
      "panels": 12,
      "price_cents": 1499,
      "currency": "usd",
      "recommended": false
    },
    {
      "id": "18",
      "label": "Standard",
      "panels": 18,
      "price_cents": 1999,
      "currency": "usd",
      "recommended": true
    },
    {
      "id": "24",
      "label": "Premium",
      "panels": 24,
      "price_cents": 2999,
      "currency": "usd",
      "recommended": false
    }
  ],
  "limits": {
    "max_characters": 4,
    "max_photos_per_character": 3
  }
}

POST /comics

Creates a draft comic from the person’s story and choices.

curl -X POST https://api.basedonus.com/connector/v1/comics \
  -H "Content-Type: application/json" \
  -d '{
  "occasion": "couple",
  "style": "superhero-comic",
  "tone": "romantic",
  "length": "18",
  "story": {
    "about": "We met at a coffee shop in Brooklyn five years ago and have been inseparable since.",
    "inside_jokes": "She still calls him \"Toast Boy\" after he set off the fire alarm making breakfast.",
    "important_memory": "The rainy hike where he proposed under a broken umbrella.",
    "things_to_include": "Their golden retriever, Biscuit.",
    "things_to_avoid": "Nothing about her ex.",
    "ending_preference": "A wedding-day flash-forward."
  },
  "characters": [
    {
      "name": "Maya",
      "role": "bride",
      "traits": "sarcastic, loyal",
      "visual_notes": "curly red hair, glasses"
    },
    {
      "name": "Diego",
      "role": "groom",
      "traits": "clumsy, devoted",
      "visual_notes": "tall, beard"
    }
  ],
  "gift_to": "Maya & Diego",
  "gift_from": "Their college roommates",
  "gift_message": "Five years down, forever to go.",
  "source": "muse"
}'

Response:

{
  "comic_id": "b7e2b6b0-2f3e-4f2a-9c34-2a6e0b1e9f21",
  "stage": "draft",
  "continue_url": "https://basedonus.com/create?resume=b7e2b6b0-2f3e-4f2a-9c34-2a6e0b1e9f21&claim=8kQnZ2f...",
  "next_steps": [
    "Open the link to add a few clear photos of each character.",
    "See a free preview panel drawn from those photos before paying anything.",
    "Pay once to unlock the full comic, a printable PDF, and a private link to share."
  ],
  "length": "18",
  "price_cents": 1999,
  "currency": "usd"
}

GET /comics/{comic_id}

The draft’s current stage, length tier and price, and its continue_url. This never returns story text, photos, or the finished comic — poll it to know when a draft has moved on, not to read what’s in it.

curl https://api.basedonus.com/connector/v1/comics/b7e2b6b0-2f3e-4f2a-9c34-2a6e0b1e9f21

{
  "comic_id": "b7e2b6b0-2f3e-4f2a-9c34-2a6e0b1e9f21",
  "stage": "preview_ready",
  "length": "18",
  "price_cents": 1999,
  "currency": "usd",
  "continue_url": "https://basedonus.com/create?resume=b7e2b6b0-2f3e-4f2a-9c34-2a6e0b1e9f21"
}

Stage values

Catalog facts

Pulled straight from the same catalog the wizard itself uses.

Occasions

Styles

Tones

Pricing & limits

• One-time price per comic, no subscription. Checkout happens on basedonus.com, by Creem (merchant of record).
• Buyers must be 18+.
• Purchasing requires sign-in; starting and previewing a comic does not.
• Digital only — nothing physical ships.
• Rate limits, per IP: 120 requests/minute for the read routes (GET /catalog, GET /comics/{comic_id}), 30/minute for POST /comics. Exceeding either returns HTTP 429.
• POST /comics is NOT idempotent — a retried call creates a second draft. Only retry it on a connection error or a 5xx, never on an ambiguous timeout.
• Errors are JSON { "detail": ... } — 422 for validation failures, 404 for an unknown comic id, 503 if the connector is temporarily unavailable.

Privacy

Uploaded photos auto-delete and are never sold or used to train models. See Privacy Policy, Terms of Service and Acceptable Use Policy.

Support

support@basedonus.com