newcharactersheet API

Quick Start

Get an API key and generate your first character in two steps.

curl -X POST https://newcharactersheet.com/api/generate \
  -H "X-API-Key: ncs_dG9rZW4..." \
  -F "prompt=A cyberpunk street samurai with neon tattoos" \
  -F "visibility=private"

{
  "id": "6d3f...",
  "imageBase64": "iVBORw0KGgo...",
  "contentType": "image/png"
}

Authentication

Sign in and create an API key from Settings. Pass it in the X-API-Key header. Keys start with ncs_.

curl https://newcharactersheet.com/api/auth/me \
  -H "X-API-Key: ncs_your_key_here"

Auth

{
  "authenticated": true,
  "uid": "fWx8k2mN..."
}

Generation

curl -X POST https://newcharactersheet.com/api/generate \
  -H "X-API-Key: ncs_..." \
  -F "prompt=A medieval knight with golden armor" \
  -F "keywords=knight,medieval,armor" \
  -F "visibility=public" \
  -F "style=anime"

{
  "id": "6d3f..."
}

{
  "prompt": "Epic battle in a volcanic landscape",
  "sheetIds": ["6d3f..."],
  "outputMode": "picture"
}

{
  "id": "s9f2...",
  "imageBase64": "iVBORw0KGgo...",
  "contentType": "image/png",
  "outputMode": "picture"
}

curl -X POST https://newcharactersheet.com/api/generate \
  -H "X-API-Key: ncs_..." \
  -F "prompt=A fire mage with flowing red robes"
# → { "id": "char_abc..." }

curl -X POST https://newcharactersheet.com/api/scene/generate \
  -H "X-API-Key: ncs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Standing on a cliff overlooking a burning city",
    "sheetIds": ["char_abc..."],
    "outputMode": "picture"
  }'
# → { "id": "scene_xyz...", "outputMode": "picture" }

curl -X POST https://newcharactersheet.com/api/scene/generate \
  -H "X-API-Key: ncs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Camera slowly pans across the burning city",
    "sheetIds": ["char_abc..."],
    "outputMode": "video"
  }'
# → { "id": "vid_001...", "outputMode": "video" }

Sheets

{
  "id": "6d3f...",
  "ownerUid": "fWx8k2mN...",
  "sheetType": "character",
  "visibility": "public",
  "prompt": "A medieval knight...",
  "keywords": ["knight", "medieval"],
  "handle": "golden-knight",
  "createdAt": 1708300000000,
  "updatedAt": 1708300000000,
  "image": {
    "storagePath": "sheets/...",
    "publicUrl": "https://...",
    "contentType": "image/png",
    "width": 2048, "height": 2048
  },
  "video": {
    "storagePath": "sheets/...",
    "publicUrl": "https://...",
    "contentType": "video/mp4"
  },
  "accessUrl": "https://...",
  "videoAccessUrl": "https://...",
  "panelCuts": [
    { "id": "c1", "x": 0, "y": 0, "width": 0.5, "height": 0.5 }
  ],
  "stats": { "savesCount": 12, "likesCount": 34, "commentsCount": 5 },
  "project": { "id": "proj_1", "name": "My Project" },
  "characterRefs": ["sheet_abc..."],
  "savedFrom": { "sheetId": "orig_1", "ownerUid": "u123" },
  "viewerHasLiked": false
}

{
  "keywords": ["knight", "medieval", "armor"],
  "handle": "golden-knight"
}

{
  "id": "6d3f...",
  "keywords": ["knight", "medieval", "armor"],
  "handle": "golden-knight"
}

{
  "results": [
    {
      "id": "6d3f...",
      "prompt": "A medieval knight...",
      "keywords": ["knight", "medieval"],
      "handle": "golden-knight",
      "imageUrl": "https://..."
    }
  ]
}

{ "visibility": "public" }

{
  "id": "6d3f...",
  "visibility": "public"
}

API Keys

{
  "keys": [
    {
      "keyId": "a1b2c3...",
      "label": "my-agent",
      "last4": "Zw4x",
      "createdAt": 1708300000000
    }
  ]
}

{ "label": "production" }

{
  "key": "ncs_dG9rZW4...",
  "keyId": "a1b2c3..."
}

{ "keyId": "a1b2c3..." }

{ "ok": true }

Rate Limits & Quotas

All API routes are rate-limited per IP address. Generation routes have stricter limits. API keys have a daily request quota.

Rate-limited responses return 429 with a Retry-After header. Quota-exceeded responses return 429 with code QUOTA_EXCEEDED.

Input Limits

Errors

All errors return a consistent shape:

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication required"
  }
}

Common codes: 401 403 404 429 500