Models
The roster is live, resolved from the registry. It is exposed as themodelId enum on each generate tool (MCP), or via contenthero model list (CLI). There is no static model list to memorize; ask for the current one.
Core operations
Reads:
list_media / get_media (spanning creations, boards, and looks via the kind filter), list_avatars / get_avatar, list_voices / get_voice.
Avatar writes: create_avatar / update_avatar / delete_avatar (CLI contenthero avatar create|update|delete). Voices stay read-only.
Async
generate_* runs a smart-wait of about 50s, then returns the finished asset or an outputId if the render is still going. Check it with get_generation_status (CLI contenthero generation status <id>), which blocks until the render finishes by default; pass wait: false, or --no-wait, for an instant snapshot. The outputId is always returned, so you can always keep polling.
Chaining outputs
A reference input (start frame, image input, audio for lip-sync) accepts a raw URL or a ContentHero output-id token<uuid>-<N>, the Nth variation of a prior output. The server resolves either, type-checks it, and scopes it to the owner.
The common chain: generate a key frame, then feed its output id straight into a video as the start frame.
1
Generate the image
generate_image with your prompt and modelId. Capture the returned output id.2
Feed it into video
generate_video with the image’s output-id token as the start frame. No re-upload needed.Cost preflight
Preview any cost for free withgetCost: true (MCP) or --cost (CLI). The preview takes the same parameters as the real call, so the quote matches the charge.
Identity and references
For consistent characters across generations, ContentHero supports avatars and reference boards as reusable identity. Browse them withlist_avatars and the board media reads, and pass them as typed references. The pipeline and the ContentHero skill cover the full reference model.
Generating into a look
An avatar owns a set of looks: one appearance of the same character, varying the outfit, setting or framing. PassavatarId to file the result onto that avatar as a new look instead of saving a standalone library output.
generate_image with avatarId, and generate_board with avatarId to file a character sheet against the avatar it was built for. Pass a reference image of the avatar alongside it to keep the subject on-model; avatarId decides where the result is filed, not what it looks like.
The avatar must be one you own. An id you do not own is rejected rather than ignored.
Managing avatars
create_avatar starts a character and generates its first look. It spends credits (preview with getCost, or --cost on the CLI), and it returns before the avatar is usable:
status: "processing" with no image. Its default look and profile photo are set when that first look finishes, so poll get_avatar (CLI contenthero avatar get <id>) until the status is completed. Credits are charged on completion, so a failed generation is not charged.
Supply referenceImageUrls (--ref, repeatable) to make the avatar a likeness of a real person from their photos. Only use photos of someone who has agreed to it.
Filing an image you already have costs nothing and is a separate operation from generating:
update_avatar, so one call can add a look and make it the default:
applied array says which ran.
Two things behave more gently than their names suggest. Removing a look trashes it, recoverable for 30 days. Deleting an avatar is soft, and its looks survive as library images, so you can file them onto another avatar afterwards. That is what makes consolidating duplicate characters safe.
Avatar writes need the studio:write scope, except create_avatar, which needs studio:generate because it charges credits.