API Reference - ContentHero

ContentHero exposes one backend surface three ways. They are the same operations under different skins.

Layer	What it is	Auth
`/api/v1`	The REST surface, base `https://app.contenthero.ai/api/v1`	API key, bearer token
`@contenthero/sdk`	A typed TypeScript kernel over `/api/v1`	API key
MCP (hosted or `@contenthero/mcp`)	The same surface as agent tools	OAuth or key
`@contenthero/cli`	The same surface as shell commands	`contenthero login` or key

Base URL and auth

https://app.contenthero.ai/api/v1

Send your API key as a bearer token:

curl https://app.contenthero.ai/api/v1/account/balance \
  -H "Authorization: Bearer $CONTENTHERO_API_KEY"

TypeScript SDK

npm install @contenthero/sdk

import { ContentHero } from "@contenthero/sdk";

const ch = new ContentHero({ apiKey: process.env.CONTENTHERO_API_KEY });

const balance = await ch.getBalance();
const result = await ch.generateImageAndWait({
  prompt: "a marble bust of an owl, studio light",
  modelId: "nano-banana-2",
});

The SDK is a hand-written kernel: typed inputs and outputs, idempotency keys, and smart-wait plus polling helpers. The MCP server and the CLI both ride it.

Conventions

Async: generation endpoints smart-wait, then return an outputId to poll at GET /studio/generate/{outputId}.
Chaining: references accept a raw URL or an output-id token <uuid>-<N>.
Cost preflight: generation accepts a cost-only mode (getCost: true) that charges nothing.
Scopes: keys are scope-gated; a 403 names the missing scope. See API Keys.
Rate limits: per-key, returning 429 when exceeded.
Idempotency: generation accepts an idempotency key so a retried request does not double-charge.

By domain

Generate

Pipeline

Brand

Inspiration

Account

These pages document the endpoints, their methods, scopes, and purpose. The authoritative contract for exact request and response shapes is the SDK types, and contenthero schema dumps every command’s input schema from the CLI.

​Base URL and auth

​TypeScript SDK

​Conventions

​By domain

Generate

Pipeline

Brand

Inspiration

Account

Base URL and auth

TypeScript SDK

Conventions

By domain