Quickstart - ContentHero

This gets you from nothing to a generated image. Pick the transport that matches how you work: an agent host with MCP, a shell with the CLI, or raw HTTP.

1. Get an API key

Create a key in the ContentHero app under Settings, API Keys. Keys are scope-gated; for generation, grant the generate scopes. Treat the key like a password.

Never paste an API key into an agent chat. The CLI and MCP handle keys for you. See Authentication.

2. Connect a transport

MCP
CLI
Raw API

Add the hosted server to your agent host. It authenticates over OAuth, so there is no key to manage.

{
  "mcpServers": {
    "contenthero": {
      "url": "https://mcp.contenthero.ai"
    }
  }
}

Your host walks you through the OAuth consent once. After that, the ContentHero tools appear as mcp__contenthero__*. See MCP setup for per-host instructions.

npm install -g @contenthero/cli
contenthero login        # browser-assisted, provisions and stores a key
contenthero auth status  # exits 0 when authenticated

The CLI stores the key at ~/.contenthero/credentials (mode 0600). You can also set CONTENTHERO_API_KEY in the environment. See CLI setup.

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

A 200 with your credit balance confirms the key works.

3. Preview the cost

Every spend can be previewed for free before you commit.

Call generate_image with getCost: true. It returns the price and charges nothing.

contenthero generate image --prompt "a marble bust of an owl, studio light" --cost

4. Generate

MCP
CLI
Raw API

Call generate_image with a prompt and a modelId. The available models are the modelId enum on the generate tools, resolved live from the registry. The call smart-waits about 50s, then returns the asset or an outputId to poll.

contenthero generate image \
  --prompt "a marble bust of an owl, studio light" \
  --model nano-banana-2

Run contenthero model list to see the live roster.

curl https://app.contenthero.ai/api/v1/studio/generate \
  -H "Authorization: Bearer $CONTENTHERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"image","prompt":"a marble bust of an owl, studio light","modelId":"nano-banana-2"}'

5. Poll if it is still rendering

If the render outlasts the smart-wait, you get an outputId. Poll it.

Call get_generation_status with the outputId for a snapshot, or wait_for_generation to block until it is done.

contenthero generation wait <outputId>

Next steps

Chain into video

Feed the image’s output id straight into generate_video as a start frame.

Run the full pipeline

Ground a post in your voice, produce the media, and schedule it.

Install the skills

Let your agent drive the whole surface with the official workflows.

Browse the recipes

End-to-end chains you can copy.

​1. Get an API key

​2. Connect a transport

​3. Preview the cost

​4. Generate

​5. Poll if it is still rendering

​Next steps

Chain into video

Run the full pipeline

Install the skills

Browse the recipes

1. Get an API key

2. Connect a transport

3. Preview the cost

4. Generate

5. Poll if it is still rendering

Next steps