> ## Documentation Index
> Fetch the complete documentation index at: https://askeditor.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Text Behind the Subject

> Put a word BEHIND the speaker so their head and shoulders cut across the letters.

Put a word BEHIND the speaker so their head and shoulders cut across the letters. Driven by the TRANSCRIPT, not by timestamps: the opening earns one word naming what the video is about, and an emphasis phrase earns the word that follows it. Three steps — preview the placements for free, matte only those moments, then apply.

## Material

One recording of a person talking, with intelligible speech: the placements are decided from the words. ANY LENGTH — matting is per-placement, so a 20-minute take costs the same as a 20-second one. The subject must be in shot, large enough in frame, and must not leave it.

## Spec

| Field      | Type                                 | Required | Description                                                                                                                                                                                                                                                                              |
| ---------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `position` | enum (`top` \| `middle` \| `bottom`) | no       | Where the word sits relative to the speaker. Omit and the plan decides per placement.                                                                                                                                                                                                    |
| `cadence`  | number                               | no       | How many moments the finished piece should carry, up to 4. Omit and you get exactly what the intro and emphasis rules earned — on a calm recording that is one, and that is correct. A target is not a guarantee: a take with nothing to say in a stretch comes back short and says why. |
| `only`     | string                               | no       | One explicit word to place, overriding both drivers. Use when the user names the word themselves.                                                                                                                                                                                        |

## Pricing & timing

|              |                                                                                                           |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| **Delivery** | **Editable canvas** — this template returns a canvas and **no mp4**. [Why](/docs/concepts/the-editable-canvas) |
| Price        | 75 credits: [estimate](/docs/setting-up/jobs-and-polling) is free and authoritative                            |
| Typical run  | \~120s                                                                                                    |
| Review gate  | No: runs straight through                                                                                 |

## Refusals this template can return

* `NO_SUBJECT`
* `SUBJECT_TOO_SMALL`
* `SUBJECT_LEAVES_FRAME`
* `UNREADABLE`

Refusals are free and typed: see [Refusals](/docs/setting-up/refusals).

## Run it

<Tabs>
  <Tab title="curl (REST)">
    ⚠️ **This template is a THREE-CALL FLOW, not one submit.** The plan is agreed
    before any GPU is spent, which is why the preview is free and the charge lands
    on step 2.

    ```bash theme={null}
    # 0. read the recording — uploads it AND transcribes, returns projectId + words
    curl -X POST https://api.askeditor.com/api/talking-head-cut/read \
      -H "Authorization: Bearer $ASKEDITOR_API_KEY" \
      -F "recording=@./recording.mp4"
    # → { "projectId": "…", "transcript": [ { "t": "word", "s": 0.1, "e": 0.4 }, … ] }

    # 1. PLAN — which word, when. FREE, changes nothing, iterate until happy
    curl -X POST https://api.askeditor.com/api/text-behind/plan \
      -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \
      -d '{ "projectId": "…", "words": [ … ], "durationSec": 165.5 }'
    # → { "placements": [ { "startSec": 0.56, "endSec": 4.56, "text": "RIGHT", "why": "the opening" } ],
    #     "quotedCredits": 75 }

    # 2. SUBJECT — matte ONLY those moments. 75 credits, charged on success
    curl -X POST https://api.askeditor.com/api/text-behind/subject \
      -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \
      -d '{ "projectId": "…", "placements": [ … ] }'
    # → { "baseUrl": "…", "cutouts": [ … ], "width": 1920, "height": 1080 }

    # 3. APPLY — write the canvas. Free
    curl -X POST https://api.askeditor.com/api/text-behind/apply \
      -H "Authorization: Bearer $ASKEDITOR_API_KEY" -H "Content-Type: application/json" \
      -d '{ "projectId": "…", "placements": [ … ], "cutouts": [ … ], "baseUrl": "…",
            "width": 1920, "height": 1080, "durationSec": 165.5 }'
    # → { "canvasId": "…", "elements": 5 }
    ```

    🚨 **Pass step 2's own `baseUrl` to step 3**, never the original upload: the
    cut-out step normalises rotation, and the two layers must agree or the subject
    comes back on its side.

    There is **no job to poll** — apply returns the canvas id directly. See
    [delivery](/docs/concepts/the-editable-canvas).
  </Tab>

  <Tab title="Agent (MCP)">
    Connected via the [MCP connector](/docs/mcp/connect)? It is one sentence:

    > "Put a word behind me in \~/Desktop/recording.mp4"

    The agent reads the recording, previews the placements for free, shows you which
    words it chose and why, then mattes and applies once you agree.
  </Tab>
</Tabs>

**Editable delivery:** Delivers an EDITABLE CANVAS and no flat mp4 — three layers: the recording, one live text element per placement, and the subject cut-out on top. The text stays draggable and re-typeable, and the occlusion is a consequence of the stacking order rather than a composite. Export the canvas when you want a file.

<Note>
  The word going BEHIND the speaker is the entire effect. A word that never passes behind them is a caption, and this template is not a caption tool.
</Note>

<Note>
  Charged 75 credits flat on the cut-out step, on success only. The flat price holds because at most 4 placements of at most 4 seconds each reach the GPU — matting is per-span, never the whole recording.
</Note>

<Note>
  Two tiers, sized against each other: the word BEHIND the subject is the headline (240px on a 1080 short edge) and the optional caption rail in FRONT sits smaller. If you turn captions on, expect both.
</Note>