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
}

Legacy flow: credits are now bought directly with NCS via POST /api/credits/checkout. Stripe no longer sells base credit packs.

{
  "packageId": "starter",
  "returnPath": "/settings"
}

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

Legacy, optional mechanic tied to a paid Stripe pack. Boost orders always burn 100% of the quoted NCS (no treasury transfer).

{
  "stripeSessionId": "cs_test_..."
}

{
  "order": {
    "orderId": "c3145f43-...",
    "packageId": "starter",
    "credits": 1000,
    "paymentKind": "credit_boost",
    "stripeSessionId": "cs_test_...",
    "priceUsd": 10,
    "tokenSymbol": "NCS",
    "tokenAmount": "250000",
    "tokenAmountRaw": "250000000000",
    "burnAmount": "250000",
    "burnAmountRaw": "250000000000",
    "burnBps": 10000,
    "treasuryAmount": "0",
    "treasuryAmountRaw": "0",
    "treasuryBps": 0,
    "buybackNetRevenueBps": 2500,
    "tokenDecimals": 6,
    "pricingMode": "twap",
    "pricingSource": "jupiter",
    "tokenUsdPrice": 0.00004,
    "tokenSpotUsdPrice": 0.000041,
    "tokenTwapUsdPrice": 0.00004,
    "twapSampleCount": 8,
    "mintAddress": "...",
    "treasuryWallet": "...",
    "memo": "NCS_CREDITS:c3145f43-...:uid",
    "expiresAt": 1760000000000
  }
}

Verifies the Solana transaction for a pending order (credit purchase or legacy burn boost) and grants the credits. The burn/treasury amounts come from the split pinned on the order at creation time.

{
  "orderId": "c3145f43-...",
  "signature": "5Ue...",
  "walletAddress": "9xQe..."
}

{
  "ok": true,
  "balance": 1300,
  "credits": 1000,
  "signature": "5Ue...",
  "tokenomics": {
    "tokenSymbol": "NCS",
    "tokenAmount": "250000",
    "burnAmount": "2500",
    "burnBps": 100,
    "treasuryAmount": "247500",
    "treasuryBps": 9900,
    "priceUsd": 10,
    "tokenUsdPrice": 0.00004,
    "pricingMode": "twap",
    "pricingSource": "jupiter"
  }
}

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