You can use the Generate Contextual Text workflow to turn an interview, tutorial, product demonstration, or any other video, into social posts, blog posts, and newsletter copy grounded in the source media. You can request all the outputs together, and use variants to get more than one version of the whole set: independent takes to choose between, or different angles you describe with instructions. See the Generate Contextual Text API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.

The workflow builds a shared editorial brief from the asset's central idea, supporting points, and concrete details, then writes each artifact from that brief. The text addresses the subject directly: a tutorial can become an instructional article, and a product demonstration can become promotional copy.

For a simple title, description, and tags workflow, use Summarize.

Create a generate-contextual-text job

An artifact is one deliverable. A variant is a named version of every requested artifact. Two variants and two artifacts produce four pieces of text. A variant's key only labels it in the results. Any difference in angle comes from its instructions.

curl https://api.mux.com/robots/v1/jobs/generate-contextual-text \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "output_language_code": "en",
      "output_steering": {
        "audience": "video developers",
        "voice": "conversational"
      },
      "variants": [
        { "key": "option_a", "instructions": "Playful voice for developers who are new to video." },
        { "key": "option_b" }
      ],
      "artifacts": [
        { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 } },
        { "key": "blog_post", "instructions": "Write a short blog post.", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" }
      ]
    }
  }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Parameters

See language support for Mux Robots for verified languages and language tags.

Variants and artifacts

Each variant and artifact needs a key: a lowercase snake_case identifier starting with a letter, up to 64 characters. Keys must be unique within each array. A key identifies the result; it does not guide generation. Use instructions to describe the angle or deliverable.

Naming a variant funny does not make it funny. Omit instructions to get independent takes on the same brief, which is useful when you want several options to choose from or test. Add instructions when each variant should take a specific angle.

Output steering applies to every variant. To give variants different voices or audiences, describe them in each variant's instructions, for example "Playful voice for developers who are new to video".

Default channel caps are 300 words for generic and linkedin, 250 words for facebook and youtube, 100 words for tiktok, 1,500 characters for instagram, and 280 characters for x. An explicit max_length overrides the default, subject to the x ceiling.

Each artifact aims for about 90% of its cap, whatever the length of the source. A one-minute video and a 15-minute video get text of about the same length, so set max_length to the length you want rather than relying on the channel default.

generic has no platform conventions; its style follows the length cap. Short caps produce a single focused piece. For a blog post, article, or newsletter entry, use generic with a max_length above 600 words and format: "markdown", as in the blog_post artifact above.

Output steering

Scope limits which transcript cues and visual context ground the text. The other controls apply best-effort writing guidance to every artifact and do not guarantee exact wording.

For example, generate copy from just the first two minutes:

{
  "parameters": {
    "asset_id": "YOUR_ASSET_ID",
    "variants": [{ "key": "main" }],
    "artifacts": [{ "key": "post", "channel": "linkedin" }],
    "output_steering": {
      "scope": { "start_time": 0, "end_time": 120 },
      "audience": "video developers",
      "voice": "professional",
      "call_to_action": "soft",
      "brand_terms": ["Mux Video"]
    }
  }
}

The selected range must contain usable transcript evidence. A range with no usable transcript cues cannot produce grounded text and the job can fail during processing.

Output

The outputs object is included once the job is completed, in the robots.v1.job.generate_contextual_text.completed webhook or the job's GET response.

Match results to your request using the variant and artifact keys. Each returned artifact in each variant counts once toward unit consumption.

Example completed job

This example uses a two-minute asset with two variants and two artifacts, consuming 1,520 units. It is the job delivered in the robots.v1.job.generate_contextual_text.completed webhook's data field and returned by GET /robots/v1/jobs/generate-contextual-text/{JOB_ID}:

{
  "data": {
    "id": "rjob_abc123",
    "workflow": "generate-contextual-text",
    "status": "completed",
    "units_consumed": 1520,
    "created_at": 1746403200,
    "updated_at": 1746403260,
    "parameters": {
      "asset_id": "YOUR_ASSET_ID",
      "output_language_code": "en",
      "output_steering": { "audience": "video developers", "voice": "conversational" },
      "variants": [
        { "key": "option_a", "instructions": "Playful voice for developers who are new to video." },
        { "key": "option_b" }
      ],
      "artifacts": [
        { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 }, "format": "plain" },
        { "key": "blog_post", "instructions": "Write a short blog post.", "channel": "generic", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" }
      ]
    },
    "outputs": {
      "variants": [
        {
          "key": "option_a",
          "artifacts": [
            { "key": "x_post", "content": "Never shipped video before? Make a direct upload, send your file, and grab the playback ID. That's the whole trip from your laptop to a working player with Mux Video." },
            { "key": "blog_post", "content": "# Your first video, start to finish\n\nGood news: getting a video from your laptop into a player takes three steps. First, create a direct upload. Once the video is ready, its playback ID connects the uploaded asset to your player." }
          ]
        },
        {
          "key": "option_b",
          "artifacts": [
            { "key": "x_post", "content": "Uploading a video and playing it are separate steps. Follow the asset until it is ready, then use its playback ID to load the player." },
            { "key": "blog_post", "content": "# Understand the upload lifecycle\n\nA direct upload creates a destination for your video. The walkthrough then follows the uploaded asset to readiness before loading it into a player." }
          ]
        }
      ]
    }
  }
}