Skip to main content
ContentHero exposes one backend surface three ways. They are the same operations under different skins.
LayerWhat it isAuth
/api/v1The REST surface, base https://app.contenthero.ai/api/v1API key, bearer token
@contenthero/sdkA typed TypeScript kernel over /api/v1API key
@contenthero/mcp / hosted MCPThe same surface as agent toolsOAuth or key
@contenthero/cliThe same surface as shell commandscontenthero login or 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 built in. The MCP server and the CLI both ride it.

​
Conventions

  • Async: generation endpoints smart-wait, then return an outputId to poll. Use the wait helpers or get_generation_status.
  • Chaining: references accept a raw URL or an output-id token <uuid>-<N>.
  • Cost preflight: every generate call has a cost-only mode that charges nothing.
  • Scopes: keys are scope-gated; a 403 names the missing scope.
  • Rate limits: per-key, returning 429 when exceeded.
A full per-endpoint reference is in progress. For now, the SDK types are the authoritative contract for request and response shapes, and contenthero schema dumps every command’s input schema from the CLI.