Documentation

Hookworth docs

Last updated: October 3, 2026

Hookworth is self-serve software. You (or your AI agent) describe a video as a JSON project; Hookworth resolves timing, voices it with licensed stock voices, renders it, runs automatic quality checks and produces controlled variations. Everything below is done by the software.

1. Projects

A project is a JSON document: format (size, fps), scenes, narration text, on-screen text and captions. Text and captions are anchored to words and sentences, so when the narration changes, timing follows automatically.

{
  "version": 1,
  "title": "Protein snack — spring launch",
  "format": { "width": 1080, "height": 1920, "fps": 30 },
  "scenes": [
    { "id": "hook",
      "narration": "Three ingredients. That's it.",
      "visual": { "type": "image", "src": "assets/product.jpg" },
      "texts": [
        { "text": "3 ingredients", "from": "word:Three", "to": "scene.end", "style": "title" }
      ] }
  ]
}

2. Command line

agent-video init my.json          # starter project
agent-video validate my.json      # free schema + timing check
agent-video voice my.json         # voice cost estimate
agent-video render my.json -o my.mp4   # render + automatic QA
agent-video qa my.json --video my.mp4  # QA report only

Output is JSON. Exit codes: 0 ok, 1 invalid input, 2 QA errors (each finding includes the exact fix).

3. AI agents (MCP)

Claude Code, Claude Desktop, Cursor and Codex connect through the Model Context Protocol:

claude mcp add hookworth -- agent-video mcp

The agent gets tools to create, validate, render, check and fix projects. With an API key it also gets the hosted tools (brand memory, experiments, variations, credits).

4. Hosted REST API

The hosted API runs renders in a queue, stores outputs, and bills in credits. The full OpenAPI specification is served at /v1/openapi.json. Authentication uses an API key per workspace; webhooks notify you when a render or experiment finishes.

5. Quality checks

Every render returns a QA report: text overflow and overlap, caption speed, scene length, frame size and rate, black frames, missing or silent audio, loudness (target −14 LUFS) and clipping.

6. Credits

1 credit = $0.10. The cost of every render or generation is shown before it starts; failed renders are refunded automatically. See pricing.

7. Content policy

No AI avatars, synthetic presenters, face swaps, deepfakes or voice cloning. Narration uses licensed stock voices; visuals come from your own footage and product images, or generated products, scenes and graphics. Full text in our Terms.

Questions: hello@gethookworth.com