newcharactersheet API

Use CREDITS for account credits, or BYO for saved provider keys. Saving a provider key switches the account to BYO mode.

{
  "mode": "CREDITS"
}

{
  "mode": "CREDITS",
  "creditsAvailable": true,
  "hasByoApiKey": false
}

Accepts multipart/form-data. In credit mode, image generation usually costs 12 credits and may be lower or higher by model tier. Credits are refunded if generation fails. Returns the new sheet ID; fetch image URLs via GET /api/sheets/:id.

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..."
}

Create a scene image featuring your characters. Scene access still follows the account feature gate; generation uses credits when the account is in CREDITS mode.

{
  "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"

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"
  }'

curl https://newcharactersheet.com/api/sheets/scene_xyz... \
  -H "X-API-Key: ncs_..."

Direct video generation endpoint. Use a prompt with sheetIds, sceneIds, a first frame, or inline reference images. In credit mode, video cost is model-tiered and charged before submit; resumable provider jobs return pending.

{
  "prompt": "Camera slowly pushes in as embers drift through the air",
  "sheetIds": ["char_abc..."],
  "sceneIds": ["scene_xyz..."],
  "durationSeconds": 5,
  "aspectRatio": "16:9",
  "modelOverride": "veo-3.1-fast-generate-preview"
}

{
  "videoUrl": "https://...",
  "contentType": "video/mp4",
  "sourceUri": null,
  "videos": [
    {
      "videoUrl": "https://...",
      "contentType": "video/mp4",
      "sourceUri": null
    }
  ],
  "textResponse": "Here's the generated video. What do you think?"
}

Pending providers may return { pending: true, providerName, providerJob }. Poll again with the same providerJob to resume.

Public sheets need no auth. Private sheets require owner auth.

{
  "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
  },
  "accessUrl": "https://...",
  "videoAccessUrl": "https://...",
  "project": { "id": "proj_1", "name": "My Project" },
  "viewerHasLiked": false
}

Returns 204 with no body.

Returns metadata only. Plaintext key secrets are never returned after creation.

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

The plaintext key is returned only once.

{ "label": "production" }

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