---
title: "Create a 'generate-contextual-text' job"
method: POST
path: "/robots/v1/jobs/generate-contextual-text"
tags: ["Generate Contextual Text"]
---

# Create a 'generate-contextual-text' job

`POST /robots/v1/jobs/generate-contextual-text`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v1/jobs/generate-contextual-text`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Generates customizable text, such as social posts, blog posts, and newsletter entries, from a Mux video or audio asset. Describe each piece of text you want as an artifact, and request named variants to get several versions of the whole set. Optional output steering limits the time range used and guides audience, voice, call to action, and brand terminology.

## Request body

- CreateGenerateContextualTextJobRequest
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` GenerateContextualTextJobParameters, required
    - `asset_id` string, required: The Mux asset ID whose transcript grounds the generated text.
    - `use_shots` boolean: When true for a video asset, generate or reuse Mux shots and attach a bounded sample of shot frames as additional visual evidence. Video assets always include a storyboard; the transcript remains authoritative. Not supported for audio-only assets.
    - `output_steering` GenerateContextualTextOutputSteering: Curated controls that apply to every generated artifact in every variant. Scope bounds execution; the other fields are best-effort writing guidance. To vary voice or audience between variants, use variant instructions.
      - `scope` object: Optional execution window in seconds on the original asset timeline. Text is grounded only in transcript cues and visual context that overlap this window.
        - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
        - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
      - `audience` string: The intended reader, used as best-effort guidance for framing, vocabulary, and assumed context.
      - `voice` 'conversational' | 'editorial' | 'playful' | 'professional': Best-effort writing voice for every generated artifact in every variant. To give variants different voices, describe the voice in each variant's instructions instead.
      - `call_to_action` 'none' | 'soft' | 'direct': Best-effort guidance for whether and how the text should invite the reader to engage further.
      - `brand_terms` string[]: Preferred brand or domain terms to use exactly when the source supports them.
    - `variants` GenerateContextualTextVariant[], required: Named versions of the complete artifact set. Every variant produces every artifact. Supports 1-5 variants with unique keys.
      - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
      - `instructions` string: Optional bounded guidance that gives this variant a deliberate angle, such as a voice, audience, or focus (for example, "Playful voice for a Gen Z audience"). Applies to every artifact in the variant. Omit it to request another independent take on the same brief.
    - `artifacts` GenerateContextualTextArtifact[], required: The deliverables to create. Every variant produces each artifact. Supports 1-5 artifacts with unique keys.
      - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
      - `instructions` string: Optional guidance specific to this artifact, such as the deliverable to write. Applies in every variant.
      - `channel` 'generic' | 'x' | 'linkedin' | 'facebook' | 'instagram' | 'tiktok' | 'youtube': Publishing channel whose conventions guide the result and set its default length: 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. generic has no platform conventions; its style follows the length cap, and a max_length above 600 words produces article-style writing such as a blog post or newsletter entry.
      - `max_length` union: Hard output cap in characters or words. Defaults to the channel's cap. Text aims for about 85% of the cap regardless of the source's length, so set the length you want rather than relying on the default. x is always capped at 280 characters, even with a word cap.
        - GenerateContextualTextCharacterMaxLength
          - `unit` 'characters', required
          - `value` integer, required
        - GenerateContextualTextWordMaxLength
          - `unit` 'words', required
          - `value` integer, required
      - `format` 'plain' | 'markdown': Whether the text may use Markdown syntax. plain contains no Markdown.
    - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
    - `output_language_code` string: BCP 47 language code for generated text. Defaults to the selected transcript track's language when available.

## Response `202`

Job queued

- GenerateContextualTextJobResponse
  - `data` GenerateContextualTextJob, required
    - `id` string, required: Unique job identifier.
    - `passthrough` string: Arbitrary string supplied at creation, returned as-is.
    - `units_consumed` integer, required: Number of Mux AI units consumed by this job.
    - `directive` JobDirectiveContext: The directive run that dispatched this job. Absent for jobs created via direct API POST.
      - `id` string, required: ID of the directive that dispatched this job.
      - `run_id` string, required: ID of the specific directive run that dispatched this job.
    - `created_at` integer, required: Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required: Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state).
    - `workflow` 'generate-contextual-text', required
    - `parameters` GenerateContextualTextJobParameters, required
      - `asset_id` string, required: The Mux asset ID whose transcript grounds the generated text.
      - `use_shots` boolean: When true for a video asset, generate or reuse Mux shots and attach a bounded sample of shot frames as additional visual evidence. Video assets always include a storyboard; the transcript remains authoritative. Not supported for audio-only assets.
      - `output_steering` GenerateContextualTextOutputSteering: Curated controls that apply to every generated artifact in every variant. Scope bounds execution; the other fields are best-effort writing guidance. To vary voice or audience between variants, use variant instructions.
        - `scope` object: Optional execution window in seconds on the original asset timeline. Text is grounded only in transcript cues and visual context that overlap this window.
          - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
          - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
        - `audience` string: The intended reader, used as best-effort guidance for framing, vocabulary, and assumed context.
        - `voice` 'conversational' | 'editorial' | 'playful' | 'professional': Best-effort writing voice for every generated artifact in every variant. To give variants different voices, describe the voice in each variant's instructions instead.
        - `call_to_action` 'none' | 'soft' | 'direct': Best-effort guidance for whether and how the text should invite the reader to engage further.
        - `brand_terms` string[]: Preferred brand or domain terms to use exactly when the source supports them.
      - `variants` GenerateContextualTextVariant[], required: Named versions of the complete artifact set. Every variant produces every artifact. Supports 1-5 variants with unique keys.
        - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
        - `instructions` string: Optional bounded guidance that gives this variant a deliberate angle, such as a voice, audience, or focus (for example, "Playful voice for a Gen Z audience"). Applies to every artifact in the variant. Omit it to request another independent take on the same brief.
      - `artifacts` GenerateContextualTextArtifact[], required: The deliverables to create. Every variant produces each artifact. Supports 1-5 artifacts with unique keys.
        - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
        - `instructions` string: Optional guidance specific to this artifact, such as the deliverable to write. Applies in every variant.
        - `channel` 'generic' | 'x' | 'linkedin' | 'facebook' | 'instagram' | 'tiktok' | 'youtube': Publishing channel whose conventions guide the result and set its default length: 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. generic has no platform conventions; its style follows the length cap, and a max_length above 600 words produces article-style writing such as a blog post or newsletter entry.
        - `max_length` union: Hard output cap in characters or words. Defaults to the channel's cap. Text aims for about 85% of the cap regardless of the source's length, so set the length you want rather than relying on the default. x is always capped at 280 characters, even with a word cap.
          - GenerateContextualTextCharacterMaxLength
            - `unit` 'characters', required
            - `value` integer, required
          - GenerateContextualTextWordMaxLength
            - `unit` 'words', required
            - `value` integer, required
        - `format` 'plain' | 'markdown': Whether the text may use Markdown syntax. plain contains no Markdown.
      - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
      - `output_language_code` string: BCP 47 language code for generated text. Defaults to the selected transcript track's language when available.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status.
    - `errors` JobError[]: Error details. Present when status is 'errored'.
      - `type` string, required: Stable public error category identifier.
      - `message` string, required: Human-readable public error message.
      - `retryable` boolean: Whether retrying this job may resolve the error.
    - `resources` Resources: Related Mux resources linked to this job.
      - `assets` SlimlineAsset[], required: Mux assets associated with this job.
        - `id` string, required: Mux asset ID.
        - `meta` object: Mux asset metadata, if available.
          - `title` string: Asset title from Mux metadata.
          - `creator_id` string: Creator identifier from Mux metadata.
          - `external_id` string: External identifier from Mux metadata.
        - `passthrough` string: Passthrough string from the Mux asset.
        - `_links` object, required: Hypermedia links for the asset.
          - `self` object, required
            - `href` string, required: URL to the Mux asset resource.
    - `outputs` GenerateContextualTextJobOutputs: Workflow results. Present when status is 'completed'.
      - `variants` GeneratedTextVariant[], required
        - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
        - `artifacts` GeneratedTextArtifact[], required
          - `key` string, required: Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.
          - `content` string, required

## Other responses

- `400`: Malformed JSON request body.
- `401`: Missing or invalid Mux credentials
- `403`: The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. A free-plan workflow or unit limit can also prevent creation. For insufficient_scope, use credentials with the required permission. If using an API access token, create a replacement token with that permission. Enabling Robots for an organization does not grant token permissions.
- `409`: Resource conflict. See the error type and messages for details.
- `422`: Asset not found or errored, missing public or signed playback access, missing or ineligible required captions, or no eligible source matching the explicit caption language.
- `500`: Server error

## Changes

- **2026-10-23** `ed6cb570d60c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v1/jobs/generate-contextual-text/post.md)

---

[API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)