This is the OpenAPI specification for the Mux Robots v1 API. ```json { "openapi": "3.1.0", "x-group-parameters": true, "info": { "title": "Mux API", "description": "Run managed AI workflows on Mux assets and automate them with Directives.", "version": "v1", "contact": { "name": "Mux DevEx", "url": "https://docs.mux.com", "email": "devex@mux.com" } }, "servers": [ { "url": "https://api.mux.com", "description": "Mux Production API" } ], "security": [ { "accessToken": [] }, { "authorizationToken": [] } ], "tags": [ { "name": "Jobs", "description": "List and cancel jobs across all workflows." }, { "name": "Analyze Structure", "description": "Generate coherent metadata, chapters, scenes, and key moments from shared asset evidence." }, { "name": "Ask Questions", "description": "Ask questions about a video and get structured answers." }, { "name": "Edit Captions", "description": "Edit an existing caption track with find-and-replace edits and optional profanity censoring." }, { "name": "Find Best Thumbnails", "description": "Sample thumbnails from a Mux Video asset, score them with AI, and select the best thumbnail candidates." }, { "name": "Find Key Moments", "description": "Identify key moments in a video." }, { "name": "Generate Chapters", "description": "Generate chapters for a video." }, { "name": "Generate Contextual Text", "description": "Generate text, such as social posts and blog posts, grounded in a video or audio asset." }, { "name": "Generate Engagement Insights", "description": "Analyze viewer engagement patterns to identify high and low engagement moments with AI-powered insights." }, { "name": "Generate Premium Captions", "description": "Generate high-quality captions for a Mux asset and upload the result as a text track." }, { "name": "Moderate", "description": "Analyze a video for inappropriate content." }, { "name": "Summarize", "description": "Generate a title, description, and tags for a video." }, { "name": "Translate Audio", "description": "Translate the audio track to another language." }, { "name": "Translate Captions", "description": "Translate captions from one language to another." }, { "name": "Directives", "description": "Define which Robots workflows should run against Mux assets, and under what conditions." } ], "paths": { "/robots/v1/directives": { "post": { "operationId": "create-directive", "summary": "Create a directive", "description": "Creates a new directive that defines which Robots workflows should run against Mux assets, and under what resource conditions.", "tags": [ "Directives" ], "requestBody": { "description": "V1 directive configuration", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveConfig" } } } }, "responses": { "201": { "description": "V1 directive created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveResponse" } } } }, "400": { "description": "Malformed or missing JSON request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "422": { "description": "Invalid directive configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "get": { "operationId": "list-directives", "summary": "List directives", "description": "Returns active v0 and v1 directive summaries, newest first. Follow each self link to retrieve the owning-version configuration.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of results to return (default 25, max 100)." }, "required": false, "description": "Maximum number of results to return (default 25, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, 1-indexed (default 1)." }, "required": false, "description": "Page number, 1-indexed (default 1).", "name": "page", "in": "query" } ], "responses": { "200": { "description": "Directive summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveListResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/directives/{DIRECTIVE_ID}": { "get": { "operationId": "get-directive", "summary": "Get a directive", "description": "Returns a v1 directive. A directive owned by v0 returns 404.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Directive ID returned by directive creation or listing (drv_...)." }, "required": true, "description": "Directive ID returned by directive creation or listing (drv_...).", "name": "DIRECTIVE_ID", "in": "path" } ], "responses": { "200": { "description": "V1 directive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "delete": { "operationId": "delete-directive", "summary": "Delete a directive", "description": "Deletes a directive. After this call, subsequent GET and LIST requests will no longer return it and new directive runs cannot be triggered for it. In-flight runs that have already read the directive config continue to completion.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Directive ID returned by directive creation or listing (drv_...)." }, "required": true, "description": "Directive ID returned by directive creation or listing (drv_...).", "name": "DIRECTIVE_ID", "in": "path" } ], "responses": { "204": { "description": "Directive deleted" }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "404": { "description": "Directive not found or already deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/directives/{DIRECTIVE_ID}/runs": { "get": { "operationId": "list-directive-runs", "summary": "List directive runs", "description": "Returns a paginated list of runs for a directive, newest first. Runs are retained for 30 days.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Directive ID returned by directive creation or listing (drv_...)." }, "required": true, "description": "Directive ID returned by directive creation or listing (drv_...).", "name": "DIRECTIVE_ID", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of results to return (default 25, max 100)." }, "required": false, "description": "Maximum number of results to return (default 25, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, 1-indexed (default 1)." }, "required": false, "description": "Page number, 1-indexed (default 1).", "name": "page", "in": "query" } ], "responses": { "200": { "description": "V1 directive runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunListResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] }, "post": { "operationId": "run-directive", "summary": "Trigger a directive run", "description": "Starts a v1 run for a v1 directive. A directive owned by v0 returns 404.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Directive ID returned by directive creation or listing (drv_...)." }, "required": true, "description": "Directive ID returned by directive creation or listing (drv_...).", "name": "DIRECTIVE_ID", "in": "path" } ], "requestBody": { "description": "Run parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunDirectiveRequest" } } } }, "responses": { "202": { "description": "V1 directive run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunResponse" } } } }, "400": { "description": "Malformed or missing JSON request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "404": { "description": "Directive not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A run for this directive is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/directives/{DIRECTIVE_ID}/runs/{RUN_ID}": { "get": { "operationId": "get-directive-run", "summary": "Get a directive run", "description": "Retrieves the status, node states, and outcome of a specific directive run. Runs are retained for 30 days.", "tags": [ "Directives" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Directive ID returned by directive creation or listing (drv_...)." }, "required": true, "description": "Directive ID returned by directive creation or listing (drv_...).", "name": "DIRECTIVE_ID", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Run ID returned by directive run creation or listing (drvrun_...)." }, "required": true, "description": "Run ID returned by directive run creation or listing (drvrun_...).", "name": "RUN_ID", "in": "path" } ], "responses": { "200": { "description": "V1 directive run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectiveRunResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs": { "get": { "operationId": "list-jobs", "summary": "List jobs", "description": "Returns a paginated list of Robots jobs, with optional filters for workflow, status, and asset_id. Jobs are automatically deleted after 30 days.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "allOf": [ { "$ref": "#/components/schemas/WorkflowName" }, { "description": "Filter by workflow name" } ] }, "required": false, "description": "Filter by workflow name", "name": "workflow", "in": "query" }, { "schema": { "allOf": [ { "$ref": "#/components/schemas/JobStatus" }, { "description": "Filter by job status" } ] }, "required": false, "description": "Filter by job status", "name": "status", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Filter by Mux asset ID" }, "required": false, "description": "Filter by Mux asset ID", "name": "asset_id", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of jobs to return (default 25, max 100)" }, "required": false, "description": "Maximum number of jobs to return (default 25, max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number (default 1)" }, "required": false, "description": "Page number (default 1)", "name": "page", "in": "query" } ], "responses": { "200": { "description": "List of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJobsResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/{JOB_ID}/cancel": { "post": { "operationId": "cancel-job", "summary": "Cancel a job", "description": "Cancels a job that is currently pending or processing.", "tags": [ "Jobs" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Job cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelJobResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Job is already in a terminal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/analyze-structure": { "post": { "operationId": "create-analyze-structure-job", "summary": "Create an 'analyze-structure' job", "description": "Creates a job that generates a coherent title, summary, tags, chapters, scenes, and key moments from shared evidence for a Mux asset.", "tags": [ "Analyze Structure" ], "requestBody": { "description": "Analyze Structure parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnalyzeStructureJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "output_language_code": "en", "output_steering": { "scope": { "start_time": 30, "end_time": 300 }, "audience": "Developers evaluating video APIs", "brand_terms": [ "Mux", "Mux Data" ], "granularity": "balanced" }, "update_asset_meta": true, "update_asset_chapters": true } } } } }, "responses": { "202": { "description": "Analyze Structure job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeStructureJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "analyze-structure", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "output_language_code": "en", "output_steering": { "scope": { "start_time": 30, "end_time": 300 }, "audience": "Developers evaluating video APIs", "brand_terms": [ "Mux", "Mux Data" ], "granularity": "balanced" }, "update_asset_meta": true, "update_asset_chapters": true } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, unsupported, missing public or signed playback access, missing required captions, or an unavailable explicit caption language", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/analyze-structure/{JOB_ID}": { "get": { "operationId": "get-analyze-structure-job", "summary": "Get an 'analyze-structure' job", "description": "Retrieves the current status and results of an Analyze Structure job. Jobs are automatically deleted after 30 days.", "tags": [ "Analyze Structure" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeStructureJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "analyze-structure", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "output_language_code": "en", "output_steering": { "scope": { "start_time": 30, "end_time": 300 }, "audience": "Developers evaluating video APIs", "brand_terms": [ "Mux", "Mux Data" ], "granularity": "balanced" }, "update_asset_meta": true, "update_asset_chapters": true }, "outputs": { "title": "A product demonstration", "summary": "A presenter explains the product.", "tags": [ "product demo" ], "chapters": [ { "start_time": 23.456, "end_time": 45.678, "title": "Demonstration" } ], "scenes": [], "key_moments": [] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/ask-questions": { "post": { "operationId": "create-ask-questions-job", "summary": "Create an 'ask-questions' job", "description": "Creates a new job that uses AI to answer questions about a Mux Video asset. Optional output steering can restrict execution to a time scope in seconds.", "tags": [ "Ask Questions" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAskQuestionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "ask-questions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, missing public or signed playback access, invalid questions, missing or ineligible required captions, or no eligible source matching the explicit caption language.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/ask-questions/{JOB_ID}": { "get": { "operationId": "get-ask-questions-job", "summary": "Get an 'ask-questions' job", "description": "Retrieves the current status and results of an 'ask-questions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Ask Questions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AskQuestionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "ask-questions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } }, "outputs": { "answers": [ { "question": "Is this video about glasses?", "answer": "no", "confidence": 0.92, "reasoning": "No glasses appear on screen and the narration does not mention eyewear.", "skipped": false }, { "question": "What is the primary subject?", "answer": "watches", "confidence": 0.88, "reasoning": "Multiple wristwatches are featured prominently throughout the video.", "skipped": false }, { "question": "Describe the primary subject in one sentence.", "answer": "A close-up showcase of luxury wristwatches arranged on a wooden display.", "confidence": 0.86, "reasoning": "Visual evidence shows several wristwatches displayed against a wooden backdrop with no other competing subjects.", "skipped": false } ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/edit-captions": { "post": { "operationId": "create-edit-captions-job", "summary": "Create an 'edit-captions' job", "description": "Creates a new job that edits an existing Mux text track using static replacements, speaker-label replacements, and optional profanity censoring. Provide at least one of `replacements`, `speaker_replacements`, or `auto_censor_profanity`.", "tags": [ "Edit Captions" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEditCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "edit-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, missing public or signed playback access, missing or ineligible caption source, invalid edit parameters, or a conflicting edited track name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/edit-captions/{JOB_ID}": { "get": { "operationId": "get-edit-captions-job", "summary": "Get an 'edit-captions' job", "description": "Retrieves the current status and results of an 'edit-captions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Edit Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "edit-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" }, "outputs": { "total_replacement_count": 5, "track_id": "text_track_789ghi", "temporary_vtt_url": "https://s3.example.com/edited.vtt?sig=abc", "replaced_track_ids": [ "text_track_456def" ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/find-best-thumbnails": { "post": { "operationId": "create-find-best-thumbnails-job", "summary": "Create a 'find-best-thumbnails' job", "description": "Creates a new job that samples thumbnails from a Mux Video asset, scores them with AI, and selects the best thumbnail candidates. Optional output_steering.scope hard-limits sampling to a time window expressed in seconds while returned timestamps stay absolute to the asset timeline. Other output steering can guide scoring strategy, explicit user intent, audience, and campaign style without changing the response schema.", "tags": [ "Find Best Thumbnails" ], "requestBody": { "description": "Find best thumbnails parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFindBestThumbnailsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 5 } } } } }, "responses": { "202": { "description": "Find best thumbnails job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindBestThumbnailsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-best-thumbnails", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 5 } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, not a video asset, missing public or signed playback ID, or scope does not contain a whole-millisecond interval within the asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/find-best-thumbnails/{JOB_ID}": { "get": { "operationId": "get-find-best-thumbnails-job", "summary": "Get a 'find-best-thumbnails' job", "description": "Retrieves the current status and results of a 'find-best-thumbnails' job. Jobs are automatically deleted after 30 days.", "tags": [ "Find Best Thumbnails" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Find best thumbnails job state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindBestThumbnailsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-best-thumbnails", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 5 }, "outputs": { "best_thumbnails": [ { "time": 23.456, "subscores": { "focus": 0.9, "face_or_action": 0.8, "composition": 0.9, "contrast_color": 0.8, "brand_fit": 0.7 }, "overall": 0.82, "description": "A presenter demonstrating the product.", "alt_text": "Presenter holding the product." } ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/find-key-moments": { "post": { "operationId": "create-find-key-moments-job", "summary": "Create a 'find-key-moments' job", "description": "Creates a new job that uses AI to identify key moments in a Mux Video asset. Set use_shots to true to automatically generate or reuse Mux shots and use visual evidence during selection, with transcript evidence incorporated when available; otherwise selection uses transcript evidence and the asset must have a caption track. Audio-only assets always use transcript evidence and require a caption track. Optional output steering can restrict execution to a time scope in seconds and guide selection strategy, title style, audience, topic taxonomy, and scoring priorities without changing the response schema. Scoped results retain absolute timestamps on the original asset timeline. 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. Audio-only analysis requires a caption source; video analysis can proceed without automatic captions when the selected mode permits it.", "tags": [ "Find Key Moments" ], "requestBody": { "description": "Key moments extraction parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFindKeyMomentsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration": { "min": 15.123, "max": 45.456 } } } } } }, "responses": { "202": { "description": "Key moments job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindKeyMomentsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-key-moments", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration": { "min": 15.123, "max": 45.456 } } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, missing required media evidence, invalid parameters, or a missing or ineligible caption source required by the asset or analysis mode. parameters.target_duration.min cannot exceed the asset duration or the duration selected by output_steering.scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/find-key-moments/{JOB_ID}": { "get": { "operationId": "get-find-key-moments-job", "summary": "Get a 'find-key-moments' job", "description": "Retrieves the current status and results of a 'find-key-moments' job. Jobs are automatically deleted after 30 days.", "tags": [ "Find Key Moments" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindKeyMomentsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "find-key-moments", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration": { "min": 15.123, "max": 45.456 } }, "outputs": { "moments": [ { "start_time": 15.123, "end_time": 45.456, "cues": [ { "start_time": 15.123, "end_time": 23.456, "text": "This is the moment everything changed." } ], "overall_score": 0.92, "title": "The Pivotal Realization", "quotable_segment": { "time": 15.123, "text": "This is the moment everything changed." }, "audible_narrative": "The speaker describes a turning point.", "notable_audible_concepts": [ "pivotal realization moment" ] } ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-chapters": { "post": { "operationId": "create-generate-chapters-job", "summary": "Create a 'generate-chapters' job", "description": "Creates a new job that uses AI to generate chapters for a Mux Video asset. Optional output steering can guide chapter style, granularity, audience, and brand terms without changing the response schema.", "tags": [ "Generate Chapters" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerateChaptersJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateChaptersJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-chapters", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, unsupported asset, missing public or signed playback access, missing or ineligible required captions, or no eligible source matching the explicit caption language.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-chapters/{JOB_ID}": { "get": { "operationId": "get-generate-chapters-job", "summary": "Get a 'generate-chapters' job", "description": "Retrieves the current status and results of a 'generate-chapters' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Chapters" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateChaptersJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-chapters", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } }, "outputs": { "chapters": [ { "start_time": 0, "title": "Introduction" } ], "asset_updates": { "chapters": { "status": "created", "track_id": "chaptersabc123def456", "replaced_track_ids": [ "old_chapters_track" ] } } } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-contextual-text": { "post": { "operationId": "create-generate-contextual-text-job", "summary": "Create a 'generate-contextual-text' job", "description": "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.", "tags": [ "Generate Contextual Text" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerateContextualTextJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "output_steering": { "audience": "Video developers", "voice": "conversational" }, "variants": [ { "key": "product_led", "instructions": "Use a promotional, product-led angle." }, { "key": "insight_led", "instructions": "Use an educational, insight-led angle." } ], "artifacts": [ { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 } }, { "key": "blog_post", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" } ] } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateContextualTextJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-contextual-text", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "output_steering": { "audience": "Video developers", "voice": "conversational" }, "variants": [ { "key": "product_led", "instructions": "Use a promotional, product-led angle." }, { "key": "insight_led", "instructions": "Use an educational, insight-led angle." } ], "artifacts": [ { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 } }, { "key": "blog_post", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" } ] } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-contextual-text/{JOB_ID}": { "get": { "operationId": "get-generate-contextual-text-job", "summary": "Get a 'generate-contextual-text' job", "description": "Retrieves the current status and generated text artifacts. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Contextual Text" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateContextualTextJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-contextual-text", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "output_steering": { "audience": "Video developers", "voice": "conversational" }, "variants": [ { "key": "product_led", "instructions": "Use a promotional, product-led angle." }, { "key": "insight_led", "instructions": "Use an educational, insight-led angle." } ], "artifacts": [ { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 } }, { "key": "blog_post", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" } ] }, "outputs": { "variants": [ { "key": "insight_led", "artifacts": [ { "key": "x_post", "content": "The hard part of repurposing video isn't generating more words. It's keeping every piece grounded in the original story." }, { "key": "blog_post", "content": "# Why video repurposing breaks down after the first draft\n\nMost content workflows treat every deliverable as a separate generation problem. A shared source keeps the whole set grounded." } ] } ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-engagement-insights": { "post": { "operationId": "create-generate-engagement-insights-job", "summary": "Create a 'generate-engagement-insights' job", "description": "Creates a new job that uses AI to analyze viewer engagement patterns and generate insights for a Mux Video asset. 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. Caption evidence is optional, including for audio-only assets without captions.", "tags": [ "Generate Engagement Insights" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGenerateEngagementInsightsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc" } } } } }, "responses": { "202": { "description": "Engagement insights job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-engagement-insights", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc" } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or missing public or signed playback ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-engagement-insights/{JOB_ID}": { "get": { "operationId": "get-generate-engagement-insights-job", "summary": "Get a 'generate-engagement-insights' job", "description": "Retrieves the current status and results of a 'generate-engagement-insights' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Engagement Insights" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current status for the requested job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-engagement-insights", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc" }, "outputs": { "moment_insights": [ { "start_time": 30.123, "end_time": 60.456, "engagement_score": 0.89, "insight": "High engagement during the demo." } ], "overall_insight": { "summary": "Engagement peaks during demonstrations.", "trends": [ "Product demos drive retention" ] } } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-premium-captions": { "post": { "operationId": "create-generate-premium-captions-job", "summary": "Create a 'generate-premium-captions' job", "description": "Creates a new job that generates high-quality captions for a Mux Video asset.", "tags": [ "Generate Premium Captions" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGeneratePremiumCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-premium-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, or a text track for the requested language already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/generate-premium-captions/{JOB_ID}": { "get": { "operationId": "get-generate-premium-captions-job", "summary": "Get a 'generate-premium-captions' job", "description": "Retrieves the current status and results of a 'generate-premium-captions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Generate Premium Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "generate-premium-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] }, "outputs": { "track_id": "enabc123def456", "language_code": "en", "detected_language_code": "en", "auto_language_confidence": 1, "temporary_srt_url": "https://storage.example.com/captions/en/abc123.srt?token=abc" } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/moderate": { "post": { "operationId": "create-moderate-job", "summary": "Create a 'moderate' job", "description": "Creates a new job that uses AI to analyze a Mux Video asset for inappropriate content. Optional output steering can restrict execution to a time scope in seconds.", "tags": [ "Moderate" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModerateJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "on_flagged": { "action": "delete_playback_ids" } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerateJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "moderate", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "on_flagged": { "action": "delete_playback_ids" } } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, missing public or signed playback access, missing or ineligible required audio captions, or no eligible source matching the explicit audio caption language.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/moderate/{JOB_ID}": { "get": { "operationId": "get-moderate-job", "summary": "Get a 'moderate' job", "description": "Retrieves the current status and results of a 'moderate' job. Jobs are automatically deleted after 30 days.", "tags": [ "Moderate" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModerateJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "moderate", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "on_flagged": { "action": "delete_playback_ids" } }, "outputs": { "thumbnail_scores": [ { "time": 0, "sexual": 0.01, "violence": 0.02 }, { "time": 30, "sexual": 0.03, "violence": 0.15 }, { "time": 60, "sexual": 0.02, "violence": 0.05 } ], "max_scores": { "sexual": 0.03, "violence": 0.15 }, "exceeds_threshold": false } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/summarize": { "post": { "operationId": "create-summarize-job", "summary": "Create a 'summarize' job", "description": "Creates a new job that uses AI to generate a title, description, and tags for a Mux Video asset. Optional output steering can restrict execution to a time scope in seconds and guide summary style, audience, brand terms, and tag taxonomy without changing the response schema.", "tags": [ "Summarize" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSummarizeJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "update_asset_meta": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "summarize", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "update_asset_meta": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/summarize/{JOB_ID}": { "get": { "operationId": "get-summarize-job", "summary": "Get a 'summarize' job", "description": "Retrieves the current status and results of a 'summarize' job. Jobs are automatically deleted after 30 days.", "tags": [ "Summarize" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummarizeJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "summarize", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "update_asset_meta": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } }, "outputs": { "title": "How to Build a Sustainable Garden in Your Backyard", "description": "A step-by-step guide to soil preparation, plant selection, and organic pest control.", "tags": [ "gardening", "sustainability", "backyard" ], "asset_updates": { "title": { "status": "updated" } } } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/translate-audio": { "post": { "operationId": "create-translate-audio-job", "summary": "Create a 'translate-audio' job", "description": "Creates a new job that translates the audio track of a Mux Video asset to another language.", "tags": [ "Translate Audio" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranslateAudioJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "output_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateAudioJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-audio", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "output_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found, missing public or signed playback ID, has no audio track, is audio-only with upload_to_mux enabled, or an audio track blocks the new one under replace_existing_tracks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/translate-audio/{JOB_ID}": { "get": { "operationId": "get-translate-audio-job", "summary": "Get a 'translate-audio' job", "description": "Retrieves the current status and results of a 'translate-audio' job. Jobs are automatically deleted after 30 days.", "tags": [ "Translate Audio" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateAudioJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-audio", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "output_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" }, "outputs": { "track_id": "esabc123def456", "temporary_audio_url": "https://storage.example.com/dubs/es/audio.m4a?token=abc123", "replaced_track_ids": [ "old_spanish_audio_track" ] } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/translate-captions": { "post": { "operationId": "create-translate-captions-job", "summary": "Create a 'translate-captions' job", "description": "Creates a new job that translates captions on a Mux Video asset from one language to another.", "tags": [ "Translate Captions" ], "requestBody": { "description": "Workflow parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTranslateCaptionsJobRequest" }, "example": { "parameters": { "asset_id": "mux_asset_123abc", "track_id": "enabc123def456", "output_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } } } } }, "responses": { "202": { "description": "Job queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-captions", "status": "pending", "units_consumed": 0, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "enabc123def456", "output_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } } } } } }, "400": { "description": "Malformed JSON request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:write.", "Use an access token that includes robots:write." ] } } } } }, "409": { "description": "Resource conflict. See the error type and messages for details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Asset not found or errored, missing public or signed playback access, missing or ineligible caption source, invalid translation parameters, or an existing track blocked by replace_existing_tracks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } }, "/robots/v1/jobs/translate-captions/{JOB_ID}": { "get": { "operationId": "get-translate-captions-job", "summary": "Get a 'translate-captions' job", "description": "Retrieves the current status and results of a 'translate-captions' job. Jobs are automatically deleted after 30 days.", "tags": [ "Translate Captions" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Robots job ID returned by job creation or listing (rjob_...)." }, "required": true, "description": "Robots job ID returned by job creation or listing (rjob_...).", "name": "JOB_ID", "in": "path" } ], "responses": { "200": { "description": "Current job status and outputs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateCaptionsJobResponse" }, "example": { "data": { "id": "rjob_example123", "workflow": "translate-captions", "status": "completed", "units_consumed": 1, "created_at": 1700000000, "updated_at": 1700000060, "parameters": { "asset_id": "mux_asset_123abc", "track_id": "enabc123def456", "output_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" }, "outputs": { "track_id": "esabc123def456", "temporary_vtt_url": "https://storage.example.com/translations/es/captions.vtt?token=abc123", "never_translate_terms_preserved": true } } } } } }, "401": { "description": "Missing or invalid Mux credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "type": "insufficient_scope", "messages": [ "This operation requires robots:read.", "Use an access token that includes robots:read." ] } } } } }, "404": { "description": "No job exists for the supplied id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "servers": [ { "url": "https://api.mux.com" } ] } } }, "components": { "schemas": { "DirectiveConfig": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable directive name." }, "subject": { "$ref": "#/components/schemas/DirectiveSubject" }, "resources": { "allOf": [ { "$ref": "#/components/schemas/DirectiveResources" }, { "description": "Resources required by dependent workflow bindings." } ] }, "bindings": { "$ref": "#/components/schemas/DirectiveBindings" } }, "required": [ "name", "subject", "bindings" ], "example": { "name": "Moderate new assets", "subject": { "type": "video.asset" }, "bindings": [ { "reference_id": "moderation", "workflow": "moderate", "parameters": { "on_flagged": { "action": "delete_playback_ids" } } } ] } }, "DirectiveSubject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "video.asset" ] } }, "required": [ "type" ], "description": "Mux asset lifecycle subject. Live streams are not supported." }, "DirectiveResources": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveResource" }, "maxItems": 50 }, "DirectiveResource": { "oneOf": [ { "$ref": "#/components/schemas/DirectiveTrackResource" }, { "$ref": "#/components/schemas/DirectiveShotsResource" } ], "discriminator": { "propertyName": "type", "mapping": { "video.asset.track": "#/components/schemas/DirectiveTrackResource", "video.asset.shots": "#/components/schemas/DirectiveShotsResource" } } }, "DirectiveTrackResource": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen resource identifier, unique within resources. Binding `inputs` entries reference this handle." }, "type": { "type": "string", "enum": [ "video.asset.track" ], "description": "A caption or audio track on the asset.", "x-stainless-const": true }, "kind": { "type": "string", "enum": [ "subtitles", "audio" ], "description": "Match subtitle text tracks or audio tracks. Other text track types are not eligible." }, "source": { "$ref": "#/components/schemas/DirectiveSource" }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code the track must match (e.g. \"en\"). When omitted, any language of the declared kind matches." } }, "required": [ "reference_id", "type", "kind" ], "example": { "reference_id": "subtitles_en", "type": "video.asset.track", "kind": "subtitles", "language_code": "en", "source": { "via": "external" } } }, "DirectiveSource": { "oneOf": [ { "$ref": "#/components/schemas/DirectiveSourceExternal" }, { "$ref": "#/components/schemas/DirectiveSourceRequired" }, { "$ref": "#/components/schemas/DirectiveSourceWorkflow" }, { "$ref": "#/components/schemas/DirectiveSourceMuxApi" } ], "discriminator": { "propertyName": "via", "mapping": { "external": "#/components/schemas/DirectiveSourceExternal", "required": "#/components/schemas/DirectiveSourceRequired", "workflow": "#/components/schemas/DirectiveSourceWorkflow", "mux_api": "#/components/schemas/DirectiveSourceMuxApi" } }, "default": { "via": "external" }, "description": "How the resource is materialized. Defaults to an external source." }, "DirectiveSourceExternal": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "external" ], "x-stainless-const": true } }, "required": [ "via" ], "description": "Wait for an externally produced resource to become ready." }, "DirectiveSourceRequired": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "required" ], "x-stainless-const": true } }, "required": [ "via" ], "description": "Require the resource to be ready when the run starts." }, "DirectiveSourceWorkflow": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "workflow" ], "x-stainless-const": true }, "binding": { "type": "string", "minLength": 1, "description": "The reference_id of the workflow binding in this directive that produces the resource." } }, "required": [ "via", "binding" ], "description": "Wait for the declared producer binding and its resource." }, "DirectiveSourceMuxApi": { "oneOf": [ { "$ref": "#/components/schemas/DirectiveSourceGenerateSubtitles" }, { "$ref": "#/components/schemas/DirectiveSourceCreateTrack" }, { "$ref": "#/components/schemas/DirectiveSourceGenerateShots" } ], "discriminator": { "propertyName": "action", "mapping": { "generate_subtitles": "#/components/schemas/DirectiveSourceGenerateSubtitles", "create_track": "#/components/schemas/DirectiveSourceCreateTrack", "generate_shots": "#/components/schemas/DirectiveSourceGenerateShots" } } }, "DirectiveSourceGenerateSubtitles": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ], "x-stainless-const": true }, "action": { "type": "string", "enum": [ "generate_subtitles" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/DirectiveSourceGenerateSubtitlesParameters" } }, "required": [ "via", "action" ], "description": "Generate subtitles from the asset audio." }, "DirectiveSourceGenerateSubtitlesParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "default": "auto", "description": "BCP 47 language code for the generated subtitles (e.g. \"en\"). Defaults to \"auto\", which detects the language from the audio." }, "source_audio_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio track to transcribe. When omitted, the first audio track on the asset is used." } }, "description": "Parameters for the generate_subtitles engine action." }, "DirectiveSourceCreateTrack": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ], "x-stainless-const": true }, "action": { "type": "string", "enum": [ "create_track" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/DirectiveSourceCreateTrackParameters" } }, "required": [ "via", "action", "parameters" ], "description": "Ingest a text subtitle track or audio track from a URL." }, "DirectiveSourceCreateTrackParameters": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Publicly reachable URL of the track file to ingest." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the track (e.g. \"en\")." }, "type": { "type": "string", "enum": [ "text", "audio" ], "description": "The kind of track to create. \"text\" tracks are ingested as subtitles." } }, "required": [ "url", "language_code", "type" ], "description": "Parameters for the create_track engine action." }, "DirectiveSourceGenerateShots": { "type": "object", "properties": { "via": { "type": "string", "enum": [ "mux_api" ], "x-stainless-const": true }, "action": { "type": "string", "enum": [ "generate_shots" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/DirectiveSourceGenerateShotsParameters" } }, "required": [ "via", "action" ], "description": "Generate the asset shot-detection output." }, "DirectiveSourceGenerateShotsParameters": { "type": "object", "properties": { "image_source": { "type": "string", "enum": [ "create_storyboards", "use_shot_midpoint" ], "default": "create_storyboards", "description": "How shot images are derived. Defaults to \"create_storyboards\"." } }, "description": "Parameters for the generate_shots engine action." }, "DirectiveShotsResource": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Customer-chosen resource identifier, unique within resources. Binding `inputs` entries reference this handle." }, "type": { "type": "string", "enum": [ "video.asset.shots" ], "description": "The asset's shot-detection output.", "x-stainless-const": true }, "source": { "$ref": "#/components/schemas/DirectiveSource" } }, "required": [ "reference_id", "type" ], "example": { "reference_id": "shots", "type": "video.asset.shots", "source": { "via": "mux_api", "action": "generate_shots", "parameters": {} } } }, "DirectiveBindings": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveBinding" }, "minItems": 1, "maxItems": 150 }, "DirectiveBinding": { "oneOf": [ { "$ref": "#/components/schemas/AnalyzeStructureDirectiveBinding" }, { "$ref": "#/components/schemas/SummarizeDirectiveBinding" }, { "$ref": "#/components/schemas/ModerateDirectiveBinding" }, { "$ref": "#/components/schemas/GenerateChaptersDirectiveBinding" }, { "$ref": "#/components/schemas/GenerateContextualTextDirectiveBinding" }, { "$ref": "#/components/schemas/EditCaptionsDirectiveBinding" }, { "$ref": "#/components/schemas/TranslateCaptionsDirectiveBinding" }, { "$ref": "#/components/schemas/TranslateAudioDirectiveBinding" }, { "$ref": "#/components/schemas/AskQuestionsDirectiveBinding" }, { "$ref": "#/components/schemas/FindKeyMomentsDirectiveBinding" }, { "$ref": "#/components/schemas/GenerateEngagementInsightsDirectiveBinding" }, { "$ref": "#/components/schemas/GeneratePremiumCaptionsDirectiveBinding" }, { "$ref": "#/components/schemas/FindBestThumbnailsDirectiveBinding" } ], "discriminator": { "propertyName": "workflow", "mapping": { "analyze-structure": "#/components/schemas/AnalyzeStructureDirectiveBinding", "summarize": "#/components/schemas/SummarizeDirectiveBinding", "moderate": "#/components/schemas/ModerateDirectiveBinding", "generate-chapters": "#/components/schemas/GenerateChaptersDirectiveBinding", "generate-contextual-text": "#/components/schemas/GenerateContextualTextDirectiveBinding", "edit-captions": "#/components/schemas/EditCaptionsDirectiveBinding", "translate-captions": "#/components/schemas/TranslateCaptionsDirectiveBinding", "translate-audio": "#/components/schemas/TranslateAudioDirectiveBinding", "ask-questions": "#/components/schemas/AskQuestionsDirectiveBinding", "find-key-moments": "#/components/schemas/FindKeyMomentsDirectiveBinding", "generate-engagement-insights": "#/components/schemas/GenerateEngagementInsightsDirectiveBinding", "generate-premium-captions": "#/components/schemas/GeneratePremiumCaptionsDirectiveBinding", "find-best-thumbnails": "#/components/schemas/FindBestThumbnailsDirectiveBinding" } } }, "AnalyzeStructureDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "analyze-structure" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/analyze-structure." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/AnalyzeStructureDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "AnalyzeStructureDirectiveBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for generated text. Auto-detected from available evidence when omitted." }, "output_steering": { "$ref": "#/components/schemas/AnalyzeStructureOutputSteering" }, "update_asset_meta": { "type": "boolean", "description": "When true, writes the generated title to asset.meta.title after analysis. Defaults to false. Best-effort: a metadata-write failure does not fail the analysis. Check outputs.asset_updates.title for the outcome." }, "update_asset_chapters": { "type": "boolean", "description": "When true, replaces or creates the asset's chapters track after analysis. Defaults to false. Best-effort: a chapters-write failure does not fail the analysis. Check outputs.asset_updates.chapters for the outcome." } }, "description": "Parameters for analyze-structure, excluding engine-supplied asset_id and source track_id where applicable." }, "AnalyzeStructureOutputSteering": { "type": "object", "properties": { "scope": { "$ref": "#/components/schemas/OutputSteeringScope" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort guidance without changing the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" }, "topic_taxonomy": { "$ref": "#/components/schemas/OutputSteeringTaxonomy" }, "granularity": { "$ref": "#/components/schemas/AnalyzeStructureGranularity" } }, "description": "Curated controls that restrict Analyze Structure execution or guide its generated metadata without exposing raw prompt editing. The scope start is inclusive, the end is exclusive, and returned timestamps remain absolute." }, "OutputSteeringScope": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning." }, "end_time": { "type": "number", "exclusiveMinimum": 0, "description": "End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end." } }, "description": "Optional media execution window. Results remain timestamped against the original media timeline." }, "OutputSteeringBrandTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "minItems": 1, "maxItems": 10, "description": "Preferred brand or domain terms to use when supported by the source content." }, "OutputSteeringTaxonomy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional customer-facing name for the taxonomy." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/OutputSteeringTaxonomyValue" }, "minItems": 1, "maxItems": 50, "description": "Controlled vocabulary values used as best-effort model guidance." }, "allow_other": { "type": "boolean", "description": "When false, the model should prefer values from the taxonomy. When true, non-taxonomy values may be used when no taxonomy value applies." } }, "required": [ "values", "allow_other" ], "description": "Controlled vocabulary used as best-effort guidance for generated labels and concepts." }, "OutputSteeringTaxonomyValue": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Canonical taxonomy value to prefer when supported by the source content." }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short explanation of when this value applies." }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 10, "description": "Accepted alternate names that should normalize to the canonical label." } }, "required": [ "label" ] }, "AnalyzeStructureGranularity": { "type": "string", "enum": [ "coarse", "balanced", "fine" ], "description": "Best-effort guidance that moves scene and chapter density together." }, "SummarizeDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "summarize" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/summarize." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/SummarizeDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "SummarizeDirectiveBindingParameters": { "type": "object", "properties": { "tone": { "type": "string", "enum": [ "neutral", "playful", "professional" ], "description": "Tone for the generated summary. \"neutral\" for straightforward analysis, \"playful\" for witty and conversational, \"professional\" for executive-level reporting." }, "output_steering": { "$ref": "#/components/schemas/SummarizeOutputSteering" }, "title_length": { "type": "integer", "minimum": 1, "description": "Maximum title length in words." }, "description_length": { "type": "integer", "minimum": 1, "description": "Maximum description length in words." }, "tag_count": { "type": "integer", "minimum": 1, "default": 10, "description": "Maximum number of tags to include in the generated output. Defaults to 10." }, "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the generated summary output (e.g. \"en\", \"fr\", \"ja\"). Auto-detected from the transcript if omitted." }, "update_asset_meta": { "type": "boolean", "description": "When true, the generated title is written to the Mux asset's metadata (asset.meta.title) once the summary completes. Best-effort: a metadata-write failure does not fail the summary." } }, "description": "Parameters for summarize, excluding engine-supplied asset_id and source track_id where applicable." }, "SummarizeOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. The summary and tags are generated only from media within this window." } ] }, "tag_taxonomy": { "$ref": "#/components/schemas/SummaryTagTaxonomy" }, "summary_style": { "$ref": "#/components/schemas/SummaryStyle" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" } }, "description": "Curated output_steering controls for execution scope, summary style, audience, brand terminology, and tag taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "SummaryTagTaxonomy": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Optional customer-facing name for the taxonomy, up to 100 characters." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Canonical tag value to prefer in generated tags, up to 100 characters." }, "description": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Short explanation of when this tag applies, up to 300 characters." }, "aliases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 10, "description": "Accepted alternate names that should normalize to the canonical label. Up to 10 aliases, each up to 100 characters." } }, "required": [ "label" ] }, "minItems": 1, "maxItems": 50, "description": "Controlled vocabulary values for generated tags. Supports 1-50 values." }, "allow_other": { "type": "boolean", "description": "When false, generated tags are filtered to taxonomy labels and aliases. When true, unmatched tags may remain." } }, "required": [ "values", "allow_other" ], "description": "Controlled vocabulary for tag generation. This steers tags and may be deterministically filtered after generation. Supports up to 50 values and 2000 serialized characters." }, "SummaryStyle": { "type": "string", "enum": [ "concise", "detailed", "editorial" ], "description": "Best-effort style guidance for the generated title and description." }, "ModerateDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "moderate" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/moderate." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/ModerateDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "ModerateDirectiveBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "Used only for audio-only transcript analysis; ignored for video assets. 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." }, "thresholds": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for violent content. Content scoring above this value triggers exceeds_threshold." } }, "default": { "sexual": 0.7, "violence": 0.8 }, "description": "Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}." }, "sampling_interval": { "type": "integer", "minimum": 5, "description": "Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints." }, "max_samples": { "type": "integer", "minimum": 1, "description": "Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned." }, "output_steering": { "$ref": "#/components/schemas/ModerateOutputSteering" }, "on_flagged": { "$ref": "#/components/schemas/ActionOnFlagged" } }, "description": "Parameters for moderate, excluding engine-supplied asset_id and source track_id where applicable." }, "ModerateOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Moderation is restricted to media within this window, while returned timestamps remain absolute asset timestamps." } ] } }, "description": "Curated controls that optionally restrict moderation to an asset time range." }, "ActionOnFlagged": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete_playback_ids" ], "description": "Action to take when exceeds_threshold is true. \"delete_playback_ids\" deletes every playback ID on the asset, making it unplayable while preserving the underlying asset so it can be re-published or reviewed." } }, "required": [ "action" ], "description": "Optional action taken automatically when exceeds_threshold is true. When omitted, the job only reports scores and takes no action. Note: in a directive run that targets the same asset with other workflows, deleting playback IDs can break sibling workflows that need a playback ID.", "example": { "action": "delete_playback_ids" } }, "GenerateChaptersDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "generate-chapters" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/generate-chapters." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/GenerateChaptersDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "GenerateChaptersDirectiveBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted." }, "output_steering": { "$ref": "#/components/schemas/GenerateChaptersOutputSteering" }, "update_asset_chapters": { "type": "boolean", "description": "When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_updates.chapters` in the job outputs for the outcome." } }, "description": "Parameters for generate-chapters, excluding engine-supplied asset_id and source track_id where applicable." }, "GenerateChaptersOutputSteering": { "type": "object", "properties": { "chapter_style": { "$ref": "#/components/schemas/ChapterStyle" }, "chapter_granularity": { "$ref": "#/components/schemas/ChapterGranularity" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" } }, "description": "Curated output_steering controls for chapter style, granularity, audience, and brand terminology. These controls guide model behavior but do not guarantee exact output." }, "ChapterStyle": { "type": "string", "enum": [ "descriptive", "punchy", "educational", "seo", "platform_neutral" ], "description": "Best-effort style guidance for generated chapter titles." }, "ChapterGranularity": { "type": "string", "enum": [ "coarse", "balanced", "fine" ], "description": "Best-effort guidance for how coarse or fine chapter boundaries should be." }, "GenerateContextualTextDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "generate-contextual-text" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/generate-contextual-text." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/GenerateContextualTextDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow", "parameters" ] }, "GenerateContextualTextDirectiveBindingParameters": { "type": "object", "properties": { "use_shots": { "type": "boolean", "description": "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": { "$ref": "#/components/schemas/GenerateContextualTextOutputSteering" }, "variants": { "$ref": "#/components/schemas/GenerateContextualTextVariants" }, "artifacts": { "$ref": "#/components/schemas/GenerateContextualTextArtifacts" }, "language_code": { "type": "string", "maxLength": 35, "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$", "description": "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": { "type": "string", "maxLength": 35, "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$", "description": "BCP 47 language code for generated text. Defaults to the selected transcript track's language when available." } }, "required": [ "variants", "artifacts" ], "description": "Parameters for generate-contextual-text, excluding engine-supplied asset_id and source track_id where applicable." }, "GenerateContextualTextOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Text is grounded only in transcript cues and visual context that overlap this window." } ] }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "The intended reader, used as best-effort guidance for framing, vocabulary, and assumed context." }, "voice": { "$ref": "#/components/schemas/GenerateContextualTextVoice" }, "call_to_action": { "$ref": "#/components/schemas/GenerateContextualTextCallToAction" }, "brand_terms": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringBrandTerms" }, { "description": "Preferred brand or domain terms to use exactly when the source supports them." } ] } }, "description": "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." }, "GenerateContextualTextVoice": { "type": "string", "enum": [ "conversational", "editorial", "playful", "professional" ], "description": "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." }, "GenerateContextualTextCallToAction": { "type": "string", "enum": [ "none", "soft", "direct" ], "description": "Best-effort guidance for whether and how the text should invite the reader to engage further." }, "GenerateContextualTextVariants": { "type": "array", "items": { "$ref": "#/components/schemas/GenerateContextualTextVariant" }, "minItems": 1, "maxItems": 5, "description": "Named versions of the complete artifact set. Every variant produces every artifact. Supports 1-5 variants with unique keys." }, "GenerateContextualTextVariant": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GenerateContextualTextKey" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 500, "description": "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." } }, "required": [ "key" ], "description": "A named version of the complete artifact set: every variant produces every artifact, so 2 variants and 2 artifacts produce 4 pieces of text. The key is an identifier only and does not steer generation; use instructions to give the variant an angle." }, "GenerateContextualTextKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*$", "description": "Customer-chosen lowercase snake_case identifier used to correlate requested and returned content.", "example": "product_led" }, "GenerateContextualTextArtifacts": { "type": "array", "items": { "$ref": "#/components/schemas/GenerateContextualTextArtifact" }, "minItems": 1, "maxItems": 5, "description": "The deliverables to create. Every variant produces each artifact. Supports 1-5 artifacts with unique keys." }, "GenerateContextualTextArtifact": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GenerateContextualTextKey" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Optional guidance specific to this artifact, such as the deliverable to write. Applies in every variant." }, "channel": { "$ref": "#/components/schemas/GenerateContextualTextChannel" }, "max_length": { "$ref": "#/components/schemas/GenerateContextualTextMaxLength" }, "format": { "$ref": "#/components/schemas/GenerateContextualTextFormat" } }, "required": [ "key" ], "description": "One deliverable, such as a social post, blog post, or newsletter entry. Every variant produces each artifact. The channel sets conventions and a default cap, max_length sets the hard cap, and format controls Markdown." }, "GenerateContextualTextChannel": { "type": "string", "enum": [ "generic", "x", "linkedin", "facebook", "instagram", "tiktok", "youtube" ], "default": "generic", "description": "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." }, "GenerateContextualTextMaxLength": { "oneOf": [ { "$ref": "#/components/schemas/GenerateContextualTextCharacterMaxLength" }, { "$ref": "#/components/schemas/GenerateContextualTextWordMaxLength" } ], "discriminator": { "propertyName": "unit", "mapping": { "characters": "#/components/schemas/GenerateContextualTextCharacterMaxLength", "words": "#/components/schemas/GenerateContextualTextWordMaxLength" } }, "description": "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": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "characters" ], "x-stainless-const": true }, "value": { "type": "integer", "minimum": 10, "maximum": 20000 } }, "required": [ "unit", "value" ], "title": "GenerateContextualTextCharacterMaxLength" }, "GenerateContextualTextWordMaxLength": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "words" ], "x-stainless-const": true }, "value": { "type": "integer", "minimum": 5, "maximum": 3000 } }, "required": [ "unit", "value" ], "title": "GenerateContextualTextWordMaxLength" }, "GenerateContextualTextFormat": { "type": "string", "enum": [ "plain", "markdown" ], "default": "plain", "description": "Whether the text may use Markdown syntax. plain contains no Markdown." }, "EditCaptionsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "edit-captions" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/edit-captions." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/EditCaptionsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "EditCaptionsDirectiveBindingParameters": { "type": "object", "properties": { "auto_censor_profanity": { "type": "object", "properties": { "detection_method": { "type": "string", "enum": [ "llm" ], "default": "llm", "description": "How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text." }, "mode": { "type": "string", "enum": [ "blank", "remove", "mask" ], "default": "blank", "description": "Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to \"blank\"." }, "always_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Additional words or short phrases that should always be censored even if the model does not detect them." }, "never_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Words or short phrases that should never be censored even if the model flags them." } }, "description": "Optional LLM-driven profanity detection and censorship rules applied to the selected caption track." }, "replacements": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Exact word or phrase to replace in cue text." }, "replace": { "type": "string", "description": "Replacement text to insert when a match is found." }, "case_sensitive": { "type": "boolean", "default": false, "description": "When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so \"gonna\" also matches \"Gonna\" and \"GONNA\"." } }, "required": [ "find", "replace" ] }, "description": "Optional static word or phrase replacements applied directly to cue text." }, "speaker_replacements": { "type": "array", "items": { "$ref": "#/components/schemas/EditCaptionsSpeakerReplacement" }, "description": "Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/EditCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset." } }, "description": "Parameters for edit-captions, excluding engine-supplied asset_id and source track_id where applicable. The engine selects the first ready subtitle in asset track order, or the single ready legacy text transcript on an audio-only asset." }, "EditCaptionsSpeakerReplacement": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Existing speaker label without the surrounding square brackets." }, "replace": { "type": "string", "minLength": 1, "description": "New speaker label without the surrounding square brackets." } }, "required": [ "find", "replace" ] }, "EditCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "replace", "fail" ], "default": "replace", "description": "What to do with the source track. Defaults to `replace`: the source is deleted and the edited track takes its place under the same name, language and closed-captions setting; no other track is touched, and the source is restored if the edited track can't be added. `fail` deletes nothing and adds the edited track alongside the source, so it requires a `track_name` different from the source's. Either way the request is rejected if a track other than the source already has the edited track's name. `replace` requires `upload_to_mux` to be true." }, "TranslateCaptionsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "translate-captions" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/translate-captions." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/TranslateCaptionsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow", "parameters" ] }, "TranslateCaptionsDirectiveBindingParameters": { "type": "object", "properties": { "track_name": { "type": "string", "minLength": 1, "description": "Name for the translated Mux text track. Defaults to \"{Language} (Auto-translated)\", e.g. \"Spanish (Auto-translated)\". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true." }, "never_translate": { "$ref": "#/components/schemas/TranslateCaptionsNeverTranslateTerms" }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateCaptionsReplaceExistingTracks" }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the translated output (e.g. \"es\", \"ja\"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language." } }, "required": [ "output_language_code" ], "description": "Parameters for translate-captions, excluding engine-supplied asset_id and source track_id where applicable. The engine selects the first eligible ready subtitle in asset track order, or the single ready legacy text transcript on an audio-only asset, whose language differs from output_language_code. Target-language comparison ignores case and region subtags, matching the track replacement rules." }, "TranslateCaptionsNeverTranslateTerms": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 100, "description": "Best-effort list of terms (brand names, proper nouns) to preserve verbatim in the translated captions. Does not guarantee exact output. Terms must not contain '<' or '>', invisible characters, or characters altered by Unicode normalization.", "example": [ "Mux", "Springfield" ] }, "TranslateCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "default": "fail", "description": "What to do when the asset already has a text track in the same language as, or with the same name as, the translated track. Defaults to `fail`, which rejects the request before any translation is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status." }, "TranslateAudioDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "translate-audio" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/translate-audio." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/TranslateAudioDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow", "parameters" ] }, "TranslateAudioDirectiveBindingParameters": { "type": "object", "properties": { "track_name": { "type": "string", "minLength": 1, "description": "Name for the dubbed Mux audio track. Defaults to \"{Language} (Auto-dubbed)\", e.g. \"Spanish (Auto-dubbed)\". Mux requires audio track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to automatically upload the translated audio track to the Mux asset. Defaults to true. Must be false for audio-only assets; the job returns downloadable audio instead." }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateAudioReplaceExistingTracks" }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the target translation language (e.g. \"es\", \"fr\", \"ja\")." } }, "required": [ "output_language_code" ], "description": "Parameters for translate-audio, excluding engine-supplied asset_id and source track_id where applicable." }, "TranslateAudioReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "default": "fail", "description": "What to do when the asset already has an audio track in the same language as, or with the same name as, the new dubbed track. Defaults to `fail`, which rejects the request before any dubbing is billed. `replace_all` deletes every such track first. Audio tracks are never auto-generated by Mux Video, so `replace_generated` behaves as `fail` here. The asset's primary audio track is never deleted. Any value other than `fail` requires `upload_to_mux` to be true. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status." }, "AskQuestionsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "ask-questions" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/ask-questions." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/AskQuestionsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow", "parameters" ] }, "AskQuestionsDirectiveBindingParameters": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The question to ask about the video content. Maximum 600 characters." }, "answer_options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "description": "Allowed answer values for this question. Defaults to [\"yes\", \"no\"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply. Each option is a short label of at most 150 characters." }, "free_form_reply": { "type": "boolean", "description": "When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output." } }, "required": [ "question" ] }, "minItems": 1, "maxItems": 50, "description": "One or more questions to ask about the video, up to 50. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer." }, "language_code": { "type": "string", "minLength": 1, "description": "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." }, "max_free_form_answer_length": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500, "description": "Max character length for free-form answers, between 1 and 1000. Ignored unless at least one question sets free_form_reply: true." }, "output_steering": { "$ref": "#/components/schemas/AskQuestionsOutputSteering" } }, "required": [ "questions" ], "description": "Parameters for ask-questions, excluding engine-supplied asset_id and source track_id where applicable." }, "AskQuestionsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Answers are generated only from media within this window, while returned timestamps remain absolute asset timestamps." } ] } }, "description": "Curated controls that optionally restrict question answering to an asset time range." }, "FindKeyMomentsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "find-key-moments" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/find-key-moments." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/FindKeyMomentsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "FindKeyMomentsDirectiveBindingParameters": { "type": "object", "properties": { "max_moments": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of key moments to extract. When omitted, defaults to 10 for assets up to one hour and 25 for longer assets." }, "use_shots": { "type": "boolean", "description": "Controls whether video assets are analyzed using Mux shots. When true, shots are generated or reused and visual evidence drives selection. When false or omitted, selection uses transcript evidence and the asset must have a caption track. Not supported for audio-only assets." }, "output_steering": { "$ref": "#/components/schemas/FindKeyMomentsOutputSteering" }, "target_duration": { "$ref": "#/components/schemas/FindKeyMomentsTargetDuration" } }, "description": "Parameters for find-key-moments, excluding engine-supplied asset_id and source track_id where applicable." }, "FindKeyMomentsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned moment timestamps remain absolute asset timestamps." } ] }, "selection_strategy": { "$ref": "#/components/schemas/KeyMomentsSelectionStrategy" }, "title_style": { "$ref": "#/components/schemas/KeyMomentsTitleStyle" }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort model guidance. Does not change the output schema." }, "brand_terms": { "$ref": "#/components/schemas/OutputSteeringBrandTerms" }, "topic_taxonomy": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringTaxonomy" }, { "description": "Controlled vocabulary used to steer notable audible concepts without changing the response schema." } ] }, "rubric_priorities": { "type": "array", "items": { "$ref": "#/components/schemas/KeyMomentsRubricPriority" }, "minItems": 1, "maxItems": 4, "description": "Rubric dimensions to use as tie-breakers after applying selection strategy. Best-effort guidance only." } }, "description": "Curated output_steering controls for execution scope, selection strategy, title style, audience, taxonomy, and rubric tie-breakers. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "KeyMomentsSelectionStrategy": { "type": "string", "enum": [ "standalone_hooks", "educational_takeaways", "story_beats", "product_moments", "speaker_highlights" ], "description": "Best-effort guidance for what qualifies as a strong standalone key moment." }, "KeyMomentsTitleStyle": { "type": "string", "enum": [ "descriptive", "punchy", "educational", "social" ], "description": "Best-effort title style guidance for generated moment titles." }, "KeyMomentsRubricPriority": { "type": "string", "enum": [ "clarity_in_isolation", "emotional_intensity", "novelty", "soundbite_quality" ] }, "FindKeyMomentsTargetDuration": { "type": "object", "properties": { "min": { "type": "number", "exclusiveMinimum": 0, "maximum": 9007199254740.99, "description": "Preferred minimum highlight duration in seconds, with millisecond precision." }, "max": { "type": "number", "exclusiveMinimum": 0, "maximum": 9007199254740.99, "description": "Preferred maximum highlight duration in seconds, with millisecond precision." } }, "required": [ "min", "max" ], "example": { "min": 15.123, "max": 45.456 }, "description": "Preferred highlight duration range in seconds. Best-effort guidance, with millisecond precision." }, "GenerateEngagementInsightsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "generate-engagement-insights" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/generate-engagement-insights." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/GenerateEngagementInsightsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "GenerateEngagementInsightsDirectiveBindingParameters": { "type": "object", "properties": {}, "description": "Parameters for generate-engagement-insights, excluding engine-supplied asset_id and source track_id where applicable.", "x-stainless-empty-object": true }, "GeneratePremiumCaptionsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "generate-premium-captions" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/generate-premium-captions." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/GeneratePremiumCaptionsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "GeneratePremiumCaptionsDirectiveBindingParameters": { "type": "object", "properties": { "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio (e.g. \"en\", \"es\"). A best-effort hint that biases transcription toward this language — it is not verified against the audio and does not guarantee the output language. When supplied, language detection is skipped and the captions are labeled with this code. The language will be auto-detected when omitted; existing tracks are then checked against `replace_existing_tracks` after transcription, so a same-language conflict errors the job at track creation instead of being rejected up front, and a deleting policy only applies when the detection is confident." }, "replace_existing_tracks": { "$ref": "#/components/schemas/GeneratePremiumCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Custom name for the uploaded Mux text track. Defaults to \"{Language} (Generated)\", e.g. \"English (Generated)\". Mux requires text track names to be unique on an asset." }, "include_speakers": { "type": "boolean", "default": false, "description": "When true, speaker labels are identified and added to each caption cue. Useful for interviews, podcasts, and multi-speaker content." }, "include_words": { "type": "boolean", "default": false, "description": "When true, word-level timestamps are exported as a JSON file accessible via temporary_words_url in the job outputs. The URL expires 7 days after the job completes. Billed at a higher unit rate." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the generated SRT to the Mux asset as a new text track. Defaults to true. When false, no track is created and `replace_existing_tracks` must be `fail`; the generated SRT remains available via `temporary_srt_url`." }, "phrases": { "$ref": "#/components/schemas/GeneratePremiumCaptionsPhrases" } }, "description": "Parameters for generate-premium-captions, excluding engine-supplied asset_id and source track_id where applicable." }, "GeneratePremiumCaptionsReplaceExistingTracks": { "type": "string", "enum": [ "fail", "replace_all", "replace_generated" ], "default": "fail", "description": "What to do when the asset already has a text track in the same language as, or with the same name as, the new caption track. Defaults to `fail`, which rejects the request before any work is billed. `replace_all` deletes every such track first. `replace_generated` deletes only Mux Video auto-generated tracks and rejects if an uploaded track is in the way. Existing tracks are matched by language ignoring region subtags, and by name ignoring case, in any status. When `language_code` is omitted the detected language is used, and tracks are only deleted when the detection is confident; otherwise the job behaves as `fail`." }, "GeneratePremiumCaptionsPhrases": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 49 }, "minItems": 1, "maxItems": 1000, "description": "Best-effort list of words or short phrases (proper nouns, product names, jargon) likely to appear in the audio, used to bias recognition toward correct spellings. Does not guarantee exact output. Each phrase may contain at most 49 characters and 5 words, and must not contain the characters <, >, {, }, [, ], or \\.", "example": [ "Mux", "API" ] }, "FindBestThumbnailsDirectiveBinding": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Binding identifier, unique within the directive. Producer references point to this identifier." }, "workflow": { "type": "string", "enum": [ "find-best-thumbnails" ], "x-stainless-const": true, "description": "Workflow identifier used by POST /robots/v1/jobs/find-best-thumbnails." }, "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Resource reference IDs that must become ready before dispatch." }, "parameters": { "$ref": "#/components/schemas/FindBestThumbnailsDirectiveBindingParameters" } }, "required": [ "reference_id", "workflow" ] }, "FindBestThumbnailsDirectiveBindingParameters": { "type": "object", "properties": { "max_thumbnails": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5, "description": "Maximum number of candidate thumbnails to return (1-5). Defaults to 5." }, "output_steering": { "$ref": "#/components/schemas/FindBestThumbnailsOutputSteering" }, "update_asset_thumbnail": { "type": "boolean", "description": "When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings." } }, "description": "Parameters for find-best-thumbnails, excluding engine-supplied asset_id and source track_id where applicable." }, "FindBestThumbnailsOutputSteering": { "type": "object", "properties": { "scope": { "allOf": [ { "$ref": "#/components/schemas/OutputSteeringScope" }, { "description": "Optional sampling window in seconds on the original asset timeline, normalized inward to whole-millisecond half-open bounds. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned thumbnail timestamps remain absolute asset timestamps." } ] }, "selection_strategy": { "$ref": "#/components/schemas/FindBestThumbnailsSelectionStrategy" }, "looking_for": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Open-ended description of what the user is explicitly looking for in candidate thumbnails. Best-effort guidance only." }, "audience": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Intended audience used as best-effort scoring guidance. Does not change the output schema." }, "campaign_style": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Short description of the campaign/channel thumbnail style to prefer when supported by the frame." }, "scoring_priorities": { "type": "array", "items": { "$ref": "#/components/schemas/FindBestThumbnailsScoringPriority" }, "minItems": 1, "maxItems": 5, "description": "Rubric criteria to emphasize in close calls. Best-effort guidance only." } }, "description": "Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output." }, "FindBestThumbnailsSelectionStrategy": { "type": "string", "enum": [ "face_or_action", "clean_composition", "high_contrast", "brand_safe", "campaign_thumbnail" ], "description": "Best-effort guidance for what kind of thumbnail candidate should score highest." }, "FindBestThumbnailsScoringPriority": { "type": "string", "enum": [ "focus", "face_or_action", "composition", "contrast_color", "brand_fit" ] }, "DirectiveResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Directive" } }, "required": [ "data" ] }, "Directive": { "allOf": [ { "$ref": "#/components/schemas/DirectiveConfig" }, { "type": "object", "properties": { "resources": { "$ref": "#/components/schemas/DirectiveResources" }, "id": { "type": "string", "description": "Opaque directive identifier (drv_...)." }, "_links": { "$ref": "#/components/schemas/DirectiveLinks" }, "created_at": { "type": "integer", "minimum": 0, "description": "Creation Unix timestamp in seconds." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Last update Unix timestamp in seconds." } }, "required": [ "resources", "id", "_links", "created_at", "updated_at" ] } ], "example": { "name": "Moderate new assets", "subject": { "type": "video.asset" }, "bindings": [ { "reference_id": "moderation", "workflow": "moderate", "parameters": { "on_flagged": { "action": "delete_playback_ids" } } } ], "id": "drv_example123", "resources": [], "_links": { "self": { "href": "/robots/v1/directives/drv_example123" } }, "created_at": 1700000000, "updated_at": 1700000000 } }, "DirectiveLinks": { "type": "object", "properties": { "self": { "$ref": "#/components/schemas/DirectiveSelfLink" } }, "required": [ "self" ] }, "DirectiveSelfLink": { "type": "object", "properties": { "href": { "type": "string", "description": "URL to the directive in its creation API version." } }, "required": [ "href" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" } }, "required": [ "error" ], "example": { "error": { "type": "validation_error", "messages": [ "parameters.asset_id: Required" ] } } }, "ErrorDetail": { "type": "object", "properties": { "type": { "type": "string", "description": "Machine-readable error type." }, "messages": { "type": "array", "items": { "type": "string" }, "description": "Individual error messages describing what went wrong." } }, "required": [ "type", "messages" ] }, "DirectiveListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveSummary" } }, "total_row_count": { "type": "integer", "minimum": 0 } }, "required": [ "data", "total_row_count" ] }, "DirectiveSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque directive identifier (drv_...)." }, "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable directive name." }, "created_at": { "type": "integer", "minimum": 0, "description": "Creation Unix timestamp in seconds." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Last update Unix timestamp in seconds." }, "_links": { "$ref": "#/components/schemas/DirectiveLinks" } }, "required": [ "id", "name", "created_at", "updated_at", "_links" ], "description": "Directive summary. Follow the self link to retrieve its configuration through its creation API version.", "example": { "id": "drv_example123", "name": "Moderate new assets", "created_at": 1700000000, "updated_at": 1700000000, "_links": { "self": { "href": "/robots/v1/directives/drv_example123" } } } }, "DirectiveRunListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveRun" } }, "total_row_count": { "type": "integer", "minimum": 0 } }, "required": [ "data", "total_row_count" ] }, "DirectiveRun": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque run identifier (drvrun_...)." }, "directive_id": { "type": "string", "description": "Opaque parent directive identifier (drv_...)." }, "subject_id": { "type": "string", "description": "Bare Mux asset ID targeted by the run." }, "status": { "type": "string", "enum": [ "pending", "dispatching", "running", "waiting", "completed", "partial", "errored" ] }, "node_states": { "$ref": "#/components/schemas/DirectiveNodeStates" }, "started_at": { "type": "integer", "minimum": 0, "description": "Run start Unix timestamp in seconds." }, "completed_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Terminal Unix timestamp in seconds, or null while in progress." } }, "required": [ "id", "directive_id", "subject_id", "status", "node_states", "started_at", "completed_at" ], "example": { "id": "drvrun_example", "directive_id": "drv_example", "subject_id": "asset_example", "status": "pending", "node_states": [], "started_at": 1746403300, "completed_at": null } }, "DirectiveNodeStates": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveNodeState" }, "maxItems": 150, "description": "Per-binding state in configuration order. Failed nodes retain their reason diagnostic." }, "DirectiveNodeState": { "oneOf": [ { "$ref": "#/components/schemas/DirectiveNodeDispatched" }, { "$ref": "#/components/schemas/DirectiveNodeFailed" }, { "$ref": "#/components/schemas/DirectiveNodeWaitingForResources" }, { "$ref": "#/components/schemas/DirectiveNodeWaitingForSourceBindings" } ], "discriminator": { "propertyName": "status", "mapping": { "dispatched": "#/components/schemas/DirectiveNodeDispatched", "failed": "#/components/schemas/DirectiveNodeFailed", "waiting_for_resources": "#/components/schemas/DirectiveNodeWaitingForResources", "waiting_for_source_bindings": "#/components/schemas/DirectiveNodeWaitingForSourceBindings" } } }, "DirectiveNodeDispatched": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding reference_id from directive.bindings[]." }, "status": { "type": "string", "enum": [ "dispatched" ], "x-stainless-const": true }, "job_id": { "type": "string", "description": "Workflow job ID (rjob_...)." }, "workflow": { "$ref": "#/components/schemas/WorkflowName" } }, "required": [ "reference_id", "status", "job_id", "workflow" ], "title": "DirectiveNodeDispatched" }, "WorkflowName": { "type": "string", "enum": [ "analyze-structure", "summarize", "generate-contextual-text", "moderate", "generate-chapters", "edit-captions", "translate-captions", "translate-audio", "ask-questions", "find-key-moments", "generate-engagement-insights", "generate-premium-captions", "find-best-thumbnails" ], "description": "The Robots workflow for this binding." }, "DirectiveNodeFailed": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding reference_id from directive.bindings[]." }, "status": { "type": "string", "enum": [ "failed" ], "x-stainless-const": true }, "reason": { "type": "string", "description": "Human-readable diagnostic explaining why the binding didn't dispatch." } }, "required": [ "reference_id", "status", "reason" ], "title": "DirectiveNodeFailed" }, "DirectiveNodeWaitingForResources": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding reference_id from directive.bindings[]." }, "status": { "type": "string", "enum": [ "waiting_for_resources" ], "x-stainless-const": true }, "workflow": { "$ref": "#/components/schemas/WorkflowName" } }, "required": [ "reference_id", "status", "workflow" ], "title": "DirectiveNodeWaitingForResources" }, "DirectiveNodeWaitingForSourceBindings": { "type": "object", "properties": { "reference_id": { "type": "string", "minLength": 1, "description": "Declared binding reference_id from directive.bindings[]." }, "status": { "type": "string", "enum": [ "waiting_for_source_bindings" ], "x-stainless-const": true }, "workflow": { "$ref": "#/components/schemas/WorkflowName" }, "source_bindings": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "reference_ids of producer bindings within this directive that must complete before this binding can dispatch." } }, "required": [ "reference_id", "status", "workflow", "source_bindings" ], "title": "DirectiveNodeWaitingForSourceBindings" }, "RunDirectiveRequest": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The bare Mux asset ID to run the directive against, as returned by the Mux Video API." } }, "required": [ "asset_id" ], "example": { "asset_id": "abc123def456" } }, "DirectiveRunResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DirectiveRun" } }, "required": [ "data" ] }, "JobStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "errored", "cancelled" ], "description": "Current job status." }, "ListJobsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobSummary" } }, "total_row_count": { "type": "integer", "minimum": 0, "description": "Total number of jobs matching the query filters", "example": 42 } }, "required": [ "data", "total_row_count" ] }, "JobSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "workflow": { "allOf": [ { "$ref": "#/components/schemas/WorkflowName" }, { "description": "Workflow type that created this job." } ] }, "status": { "$ref": "#/components/schemas/JobStatus" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "URL to this resource." } }, "required": [ "href" ] } }, "required": [ "self" ], "description": "Hypermedia links for this job." } }, "required": [ "id", "workflow", "status", "created_at", "updated_at", "_links" ] }, "CancelJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/JobSummary" } }, "required": [ "data" ] }, "CreateAnalyzeStructureJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/AnalyzeStructureJobParameters" } }, "required": [ "parameters" ] }, "AnalyzeStructureJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze." }, "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for generated text. Auto-detected from available evidence when omitted." }, "output_steering": { "$ref": "#/components/schemas/AnalyzeStructureOutputSteering" }, "update_asset_meta": { "type": "boolean", "description": "When true, writes the generated title to asset.meta.title after analysis. Defaults to false. Best-effort: a metadata-write failure does not fail the analysis. Check outputs.asset_updates.title for the outcome." }, "update_asset_chapters": { "type": "boolean", "description": "When true, replaces or creates the asset's chapters track after analysis. Defaults to false. Best-effort: a chapters-write failure does not fail the analysis. Check outputs.asset_updates.chapters for the outcome." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "language_code": "en", "output_language_code": "en", "output_steering": { "scope": { "start_time": 30, "end_time": 300 }, "audience": "Developers evaluating video APIs", "brand_terms": [ "Mux", "Mux Data" ], "granularity": "balanced" }, "update_asset_meta": true, "update_asset_chapters": true } }, "AnalyzeStructureJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AnalyzeStructureJob" } }, "required": [ "data" ] }, "AnalyzeStructureJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "analyze-structure" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/AnalyzeStructureJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/AnalyzeStructureJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "JobDirectiveContext": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the directive that dispatched this job." }, "run_id": { "type": "string", "description": "ID of the specific directive run that dispatched this job." } }, "required": [ "id", "run_id" ], "description": "The directive run that dispatched this job. Absent for jobs created via direct API POST." }, "JobError": { "type": "object", "properties": { "type": { "type": "string", "description": "Stable public error category identifier." }, "message": { "type": "string", "description": "Human-readable public error message." }, "retryable": { "type": "boolean", "description": "Whether retrying this job may resolve the error." } }, "required": [ "type", "message" ] }, "Resources": { "type": "object", "properties": { "assets": { "type": "array", "items": { "$ref": "#/components/schemas/SlimlineAsset" }, "description": "Mux assets associated with this job." } }, "required": [ "assets" ], "example": { "assets": [ { "id": "abc123asset", "meta": { "title": "My Video", "creator_id": "user123", "external_id": "ext456" }, "_links": { "self": { "href": "/video/v1/assets/abc123asset" } } } ] }, "description": "Related Mux resources linked to this job." }, "SlimlineAsset": { "type": "object", "properties": { "id": { "type": "string", "description": "Mux asset ID." }, "meta": { "type": "object", "properties": { "title": { "type": "string", "description": "Asset title from Mux metadata." }, "creator_id": { "type": "string", "description": "Creator identifier from Mux metadata." }, "external_id": { "type": "string", "description": "External identifier from Mux metadata." } }, "description": "Mux asset metadata, if available." }, "passthrough": { "type": "string", "description": "Passthrough string from the Mux asset." }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "description": "URL to the Mux asset resource." } }, "required": [ "href" ] } }, "required": [ "self" ], "description": "Hypermedia links for the asset." } }, "required": [ "id", "_links" ] }, "AnalyzeStructureJobOutputs": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Generated title for the analyzed media." }, "summary": { "type": "string", "minLength": 1, "description": "Generated summary of the analyzed media." }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Generated tags. Always present and empty when no tag qualifies." }, "chapters": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureChapter" }, "description": "Generated chapters in timeline order. Always present and empty below the chapter threshold." }, "scenes": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureScene" }, "description": "Generated scenes in timeline order. Always present and empty for audio-only media." }, "key_moments": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureKeyMoment" }, "description": "Generated key moments in timeline order. Always present and empty when no moment qualifies." }, "asset_updates": { "$ref": "#/components/schemas/AnalyzeStructureAssetUpdateOutcomes" } }, "required": [ "title", "summary", "tags", "chapters", "scenes", "key_moments" ], "example": { "title": "A product demonstration", "summary": "A presenter explains the product.", "tags": [ "product demo" ], "chapters": [ { "start_time": 23.456, "end_time": 45.678, "title": "Demonstration" } ], "scenes": [], "key_moments": [] }, "description": "Workflow results. Present when status is 'completed'." }, "AnalyzeStructureChapter": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Chapter start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Chapter end time in seconds on the original asset timeline. Fractional seconds are supported." }, "title": { "type": "string", "minLength": 1, "description": "Concise chapter title." } }, "required": [ "start_time", "end_time", "title" ] }, "AnalyzeStructureScene": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Scene start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Scene end time in seconds on the original asset timeline. Fractional seconds are supported." }, "title": { "type": "string", "minLength": 1, "description": "Short human-readable title for the scene." }, "cues": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureCue" }, "description": "Transcript cues overlapping this scene. Empty when no usable transcript evidence is available." }, "audible_narrative": { "type": "string", "minLength": 1, "description": "Summary of what is said during the scene, when transcript evidence supports one." }, "visual_narrative": { "type": "string", "minLength": 1, "description": "Summary of what visually happens during the scene." }, "blended_narrative": { "type": "string", "minLength": 1, "description": "Combined audible and visual takeaway when both evidence types are meaningfully present." }, "notable_audible_concepts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureConcept" }, "minItems": 1, "description": "Evidence-grounded concepts from the audible content." }, "notable_visual_concepts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureVisualConcept" }, "minItems": 1, "description": "Scored concepts from the visual content." }, "shots": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureShot" }, "minItems": 1, "description": "Optional ordered shot or beat breakdown within the scene." }, "shot_count": { "type": "integer", "exclusiveMinimum": 0, "description": "Number of source shots or visual beats grouped into the scene." } }, "required": [ "start_time", "end_time", "title", "cues", "shot_count" ] }, "AnalyzeStructureCue": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Cue start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Cue end time in seconds on the original asset timeline. Fractional seconds are supported." }, "text": { "type": "string", "minLength": 1, "description": "Transcript text for this cue." } }, "required": [ "start_time", "end_time", "text" ] }, "AnalyzeStructureConcept": { "type": "string", "minLength": 3 }, "AnalyzeStructureVisualConcept": { "type": "object", "properties": { "concept": { "allOf": [ { "$ref": "#/components/schemas/AnalyzeStructureConcept" }, { "description": "Evidence-grounded visual concept containing 2-5 words." } ] }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score from 0.0 to 1.0." }, "rationale": { "type": "string", "minLength": 1, "description": "Brief explanation of the relevance score." } }, "required": [ "concept", "score", "rationale" ] }, "AnalyzeStructureShot": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Shot or beat start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Shot or beat end time in seconds on the original asset timeline. Fractional seconds are supported." }, "visual_description": { "type": "string", "minLength": 1, "description": "Short description of what happens during this shot or beat." } }, "required": [ "start_time", "end_time", "visual_description" ] }, "AnalyzeStructureKeyMoment": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Key moment start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Key moment end time in seconds on the original asset timeline. Fractional seconds are supported." }, "overall_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall evidence-grounded quality score from 0.0 to 1.0." }, "title": { "type": "string", "minLength": 1, "description": "Short title for the key moment." }, "cues": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureCue" }, "description": "Transcript cues overlapping this key moment. Empty when no usable transcript evidence is available." }, "quotable_segment": { "$ref": "#/components/schemas/AnalyzeStructureQuotableSegment" }, "audible_narrative": { "type": "string", "minLength": 1, "description": "Summary of what is said during the moment." }, "notable_audible_concepts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureConcept" }, "minItems": 1, "description": "Evidence-grounded concepts from the audible content." }, "visual_narrative": { "type": "string", "minLength": 1, "description": "Summary of what visually happens during the moment." }, "notable_visual_concepts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyzeStructureVisualConcept" }, "minItems": 1, "description": "Scored concepts from the visual content." } }, "required": [ "start_time", "end_time", "overall_score", "title", "cues" ] }, "AnalyzeStructureQuotableSegment": { "type": "object", "properties": { "time": { "type": "number", "minimum": 0, "description": "Quote start time in seconds on the original asset timeline. Fractional seconds are supported." }, "text": { "type": "string", "minLength": 1, "description": "Verbatim transcript quote selected from the key moment." } }, "required": [ "time", "text" ], "description": "Best short verbatim quote from the moment when one is supported." }, "AnalyzeStructureAssetUpdateOutcomes": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/AnalyzeStructureTitleAssetUpdate" }, "chapters": { "$ref": "#/components/schemas/AnalyzeStructureChaptersAssetUpdate" } }, "description": "Best-effort outcomes for attempted asset updates. Omitted when no update was attempted, including when only chapters were requested but none were generated." }, "AnalyzeStructureTitleAssetUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "updated", "failed" ], "description": "Outcome of the requested asset title update." } }, "required": [ "status" ], "description": "Present when a title update was requested." }, "AnalyzeStructureChaptersAssetUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "created", "failed" ], "description": "Outcome of the requested chapters track update." }, "track_id": { "type": "string", "minLength": 1, "description": "ID of the newly created chapters track." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "required": [ "status" ], "description": "Present when a chapters update was attempted. Omitted when no chapters were generated; any existing chapters track is left unchanged. When status is `failed` and replaced_track_ids is nonempty, deletion succeeded but replacement creation failed, leaving the asset without a chapters track." }, "ReplacedTrackIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "IDs of tracks deleted during replacement. Omitted when no deletions were recorded; historical jobs may lack this information." }, "CreateAskQuestionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/AskQuestionsJobParameters" } }, "required": [ "parameters" ] }, "AskQuestionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze." }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 600, "description": "The question to ask about the video content. Maximum 600 characters." }, "answer_options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "description": "Allowed answer values for this question. Defaults to [\"yes\", \"no\"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply. Each option is a short label of at most 150 characters." }, "free_form_reply": { "type": "boolean", "description": "When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output." } }, "required": [ "question" ] }, "minItems": 1, "maxItems": 50, "description": "One or more questions to ask about the video, up to 50. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer." }, "language_code": { "type": "string", "minLength": 1, "description": "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." }, "max_free_form_answer_length": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 500, "description": "Max character length for free-form answers, between 1 and 1000. Ignored unless at least one question sets free_form_reply: true." }, "output_steering": { "$ref": "#/components/schemas/AskQuestionsOutputSteering" } }, "required": [ "asset_id", "questions" ], "example": { "asset_id": "mux_asset_123abc", "questions": [ { "question": "Is this video about glasses?" }, { "question": "What is the primary subject?", "answer_options": [ "glasses", "watches", "shoes", "hats" ] }, { "question": "Describe the primary subject in one sentence.", "free_form_reply": true } ], "max_free_form_answer_length": 300, "output_steering": { "scope": { "start_time": 30, "end_time": 180 } } } }, "AskQuestionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AskQuestionsJob" } }, "required": [ "data" ] }, "AskQuestionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "ask-questions" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/AskQuestionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/AskQuestionsJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "AskQuestionsJobOutputs": { "type": "object", "properties": { "answers": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "description": "The original question that was asked." }, "answer": { "type": [ "string", "null" ], "minLength": 1, "description": "For enum questions, constrained to one of the provided answer_options. For free-form questions, responds with prose up to max_free_form_answer_length characters - treat as untrusted model output. Null when the question was skipped." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Confidence score from 0.0 to 1.0. Values above 0.9 indicate clear, unambiguous evidence; 0.7-0.9 strong evidence with minor ambiguity; 0.5-0.7 moderate evidence; below 0.5 weak or uncertain evidence. Always 0 when skipped." }, "reasoning": { "type": "string", "minLength": 1, "description": "Explanation citing specific visual or audio evidence from the video, or why the question was skipped." }, "skipped": { "type": "boolean", "description": "Whether the question was skipped due to irrelevance to the video content." } }, "required": [ "question", "answer", "confidence", "reasoning", "skipped" ] }, "minItems": 1, "description": "One answer per question, in the same order as the input questions." } }, "required": [ "answers" ], "example": { "answers": [ { "question": "Is this video about glasses?", "answer": "no", "confidence": 0.92, "reasoning": "No glasses appear on screen and the narration does not mention eyewear.", "skipped": false }, { "question": "What is the primary subject?", "answer": "watches", "confidence": 0.88, "reasoning": "Multiple wristwatches are featured prominently throughout the video.", "skipped": false }, { "question": "Describe the primary subject in one sentence.", "answer": "A close-up showcase of luxury wristwatches arranged on a wooden display.", "confidence": 0.86, "reasoning": "Visual evidence shows several wristwatches displayed against a wooden backdrop with no other competing subjects.", "skipped": false } ] }, "description": "Workflow results. Present when status is 'completed'." }, "CreateEditCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/EditCaptionsJobParameters" } }, "required": [ "parameters" ] }, "EditCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID whose existing text track should be edited." }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the source captions. Must identify a ready subtitle track, or the single ready legacy text transcript without subtitle metadata on an audio-only asset. A missing or unready source is rejected." }, "auto_censor_profanity": { "type": "object", "properties": { "detection_method": { "type": "string", "enum": [ "llm" ], "default": "llm", "description": "How profanity is detected. Currently only `llm` is supported, which uses an LLM to identify profanity in cue text." }, "mode": { "type": "string", "enum": [ "blank", "remove", "mask" ], "default": "blank", "description": "Replacement strategy for detected profanity: blank inserts bracketed underscores, remove drops the match, and mask replaces characters with question marks. Defaults to \"blank\"." }, "always_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Additional words or short phrases that should always be censored even if the model does not detect them." }, "never_censor": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Words or short phrases that should never be censored even if the model flags them." } }, "description": "Optional LLM-driven profanity detection and censorship rules applied to the selected caption track." }, "replacements": { "type": "array", "items": { "type": "object", "properties": { "find": { "type": "string", "minLength": 1, "description": "Exact word or phrase to replace in cue text." }, "replace": { "type": "string", "description": "Replacement text to insert when a match is found." }, "case_sensitive": { "type": "boolean", "default": false, "description": "When true, `find` is matched only with exact case. Defaults to false (case-insensitive matching), so \"gonna\" also matches \"Gonna\" and \"GONNA\"." } }, "required": [ "find", "replace" ] }, "description": "Optional static word or phrase replacements applied directly to cue text." }, "speaker_replacements": { "type": "array", "items": { "$ref": "#/components/schemas/EditCaptionsSpeakerReplacement" }, "description": "Optional replacements for bracketed speaker labels at the start of caption cues. Values omit the surrounding square brackets, and matching spoken text is not changed." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the edited VTT back to the Mux asset as a text track. Defaults to true." }, "replace_existing_tracks": { "$ref": "#/components/schemas/EditCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the edited Mux text track. Defaults to the source track's name. Required and must differ from the source's name when `replace_existing_tracks` is `fail`. Mux requires text track names to be unique on an asset." } }, "required": [ "asset_id", "track_id" ], "example": { "asset_id": "mux_asset_123abc", "track_id": "text_track_456def", "replacements": [ { "find": "Mucks", "replace": "Mux", "case_sensitive": true }, { "find": "gonna", "replace": "going to" } ], "speaker_replacements": [ { "find": "speaker_0", "replace": "Alice" } ], "upload_to_mux": true, "replace_existing_tracks": "replace" } }, "EditCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EditCaptionsJob" } }, "required": [ "data" ] }, "EditCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "edit-captions" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/EditCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/EditCaptionsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "EditCaptionsJobOutputs": { "type": "object", "properties": { "total_replacement_count": { "type": "integer", "minimum": 0, "description": "Total count of cue text replacements applied across all edit operations." }, "temporary_vtt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL for downloading the edited VTT file. Expires 7 days after the job completes." }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the newly created edited captions, distinct from the source parameters.track_id. Present when upload_to_mux is true and the upload succeeds." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "required": [ "total_replacement_count" ], "example": { "total_replacement_count": 5, "track_id": "text_track_789ghi", "temporary_vtt_url": "https://s3.example.com/edited.vtt?sig=abc", "replaced_track_ids": [ "text_track_456def" ] }, "description": "Workflow results. Present when status is completed." }, "CreateFindBestThumbnailsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/FindBestThumbnailsJobParameters" } }, "required": [ "parameters" ] }, "FindBestThumbnailsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to find thumbnails for." }, "max_thumbnails": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5, "description": "Maximum number of candidate thumbnails to return (1-5). Defaults to 5." }, "output_steering": { "$ref": "#/components/schemas/FindBestThumbnailsOutputSteering" }, "update_asset_thumbnail": { "type": "boolean", "description": "When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "max_thumbnails": 5 } }, "FindBestThumbnailsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FindBestThumbnailsJob" } }, "required": [ "data" ], "example": { "data": { "id": "rjob_example", "workflow": "find-best-thumbnails", "parameters": { "asset_id": "mux_asset_123abc", "max_thumbnails": 5 }, "status": "completed", "units_consumed": 1, "created_at": 1750000000, "updated_at": 1750000010, "outputs": { "best_thumbnails": [ { "time": 23.456, "overall": 0.82, "subscores": { "focus": 0.9, "face_or_action": 0.8, "composition": 0.9, "contrast_color": 0.8, "brand_fit": 0.7 }, "description": "A presenter demonstrating the product.", "alt_text": "Presenter holding the product." } ] } } } }, "FindBestThumbnailsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "find-best-thumbnails" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/FindBestThumbnailsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/FindBestThumbnailsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "FindBestThumbnailsJobOutputs": { "type": "object", "properties": { "asset_updates": { "$ref": "#/components/schemas/FindBestThumbnailsAssetUpdateOutcomes" }, "best_thumbnails": { "type": "array", "items": { "$ref": "#/components/schemas/FindBestThumbnailsCandidate" }, "description": "Selected thumbnails, ordered best to worst by overall quality score." } }, "required": [ "best_thumbnails" ], "example": { "best_thumbnails": [ { "time": 23.456, "subscores": { "focus": 0.9, "face_or_action": 0.8, "composition": 0.9, "contrast_color": 0.8, "brand_fit": 0.7 }, "overall": 0.82, "description": "A presenter demonstrating the product.", "alt_text": "Presenter holding the product." } ] }, "description": "Workflow results. Present when status is completed." }, "FindBestThumbnailsAssetUpdateOutcomes": { "type": "object", "properties": { "thumbnail": { "$ref": "#/components/schemas/FindBestThumbnailsThumbnailAssetUpdate" } }, "description": "Recorded asset thumbnail update outcome. Omitted when no outcome was recorded, including historical jobs." }, "FindBestThumbnailsThumbnailAssetUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "updated", "failed" ], "description": "Outcome of the requested asset thumbnail update." } }, "required": [ "status" ] }, "FindBestThumbnailsCandidate": { "type": "object", "properties": { "subscores": { "type": "object", "properties": { "focus": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sharpness and focus quality score (0-1)." }, "face_or_action": { "type": "number", "minimum": 0, "maximum": 1, "description": "Presence of faces or dynamic action score (0-1)." }, "composition": { "type": "number", "minimum": 0, "maximum": 1, "description": "Visual composition and framing quality score (0-1)." }, "contrast_color": { "type": "number", "minimum": 0, "maximum": 1, "description": "Color contrast and vibrancy score (0-1)." }, "brand_fit": { "type": "number", "minimum": 0, "maximum": 1, "description": "Alignment with brand guidelines score (0-1)." } }, "required": [ "focus", "face_or_action", "composition", "contrast_color", "brand_fit" ], "description": "Per-category quality scores." }, "overall": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall quality score from 0 to 1." }, "description": { "type": "string", "description": "AI-generated description of the frame content." }, "alt_text": { "type": "string", "minLength": 1, "maxLength": 250, "description": "Suggested alternative text for the candidate thumbnail image, suitable for use with the thumbnail URL in an accessible UI." }, "time": { "type": "number", "minimum": 0, "description": "Absolute frame timestamp in seconds on the original asset timeline. Fractional seconds are supported." } }, "required": [ "subscores", "overall", "description", "time" ] }, "CreateFindKeyMomentsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/FindKeyMomentsJobParameters" } }, "required": [ "parameters" ] }, "FindKeyMomentsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze." }, "max_moments": { "type": "integer", "minimum": 1, "maximum": 25, "description": "Maximum number of key moments to extract. When omitted, defaults to 10 for assets up to one hour and 25 for longer assets." }, "use_shots": { "type": "boolean", "description": "Controls whether video assets are analyzed using Mux shots. When true, shots are generated or reused and visual evidence drives selection. When false or omitted, selection uses transcript evidence and the asset must have a caption track. Not supported for audio-only assets." }, "output_steering": { "$ref": "#/components/schemas/FindKeyMomentsOutputSteering" }, "target_duration": { "$ref": "#/components/schemas/FindKeyMomentsTargetDuration" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "max_moments": 10, "target_duration": { "min": 15.123, "max": 45.456 } } }, "FindKeyMomentsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FindKeyMomentsJob" } }, "required": [ "data" ] }, "FindKeyMomentsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "find-key-moments" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/FindKeyMomentsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/FindKeyMomentsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "FindKeyMomentsJobOutputs": { "type": "object", "properties": { "moments": { "type": "array", "items": { "$ref": "#/components/schemas/FindKeyMoments" }, "description": "Extracted key moments, ordered by their absolute position on the original asset timeline." } }, "required": [ "moments" ], "example": { "moments": [ { "start_time": 15.123, "end_time": 45.456, "cues": [ { "start_time": 15.123, "end_time": 23.456, "text": "This is the moment everything changed." } ], "overall_score": 0.92, "title": "The Pivotal Realization", "quotable_segment": { "time": 15.123, "text": "This is the moment everything changed." }, "audible_narrative": "The speaker describes a turning point.", "notable_audible_concepts": [ "pivotal realization moment" ] } ] }, "description": "Workflow results. Present when status is completed." }, "FindKeyMoments": { "type": "object", "properties": { "cues": { "type": "array", "items": { "$ref": "#/components/schemas/FindKeyMomentsCue" }, "description": "Contiguous transcript segments that comprise this moment. Empty when video selection identifies the moment without transcript evidence." }, "overall_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Weighted quality score from 0.0 to 1.0 based on the audible and/or visual evidence available to the selected analysis mode." }, "title": { "type": "string", "minLength": 1, "description": "Short catchy title for the moment (3-8 words)." }, "quotable_segment": { "$ref": "#/components/schemas/FindKeyMomentsQuotableSegment" }, "audible_narrative": { "type": "string", "description": "One-sentence summary of what is being said during the moment. Empty when no transcript evidence is available." }, "notable_audible_concepts": { "type": "array", "items": { "type": "string", "minLength": 3 }, "description": "Multi-word descriptive phrases (2-5 words each) capturing key audible concepts. Empty when no transcript evidence is available." }, "visual_narrative": { "type": "string", "minLength": 1, "description": "One-sentence summary of what is visually happening. Present for video assets only." }, "notable_visual_concepts": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string", "minLength": 3, "description": "Multi-word visual concept (2-5 words)." }, "score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Relevance score from 0.0 to 1.0 measuring how important the visual concept is to the moment's available evidence." }, "rationale": { "type": "string", "minLength": 1, "description": "Brief explanation of the relevance score." } }, "required": [ "concept", "score", "rationale" ] }, "minItems": 1, "description": "Scored visual concepts extracted from sampled frames. Present for video assets only." }, "start_time": { "type": "number", "minimum": 0, "description": "Key moment start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Key moment end time in seconds on the original asset timeline. Fractional seconds are supported." } }, "required": [ "cues", "overall_score", "title", "audible_narrative", "notable_audible_concepts", "start_time", "end_time" ] }, "FindKeyMomentsCue": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Transcript text for this cue." }, "start_time": { "type": "number", "minimum": 0, "description": "Cue start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Cue end time in seconds on the original asset timeline. Fractional seconds are supported." } }, "required": [ "text", "start_time", "end_time" ] }, "FindKeyMomentsQuotableSegment": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Verbatim transcript quote selected from within the key moment." }, "time": { "type": "number", "minimum": 0, "description": "Quote start timestamp in seconds on the original asset timeline. Fractional seconds are supported." } }, "required": [ "text", "time" ], "example": { "time": 23.456, "text": "We realized the entire approach was wrong." }, "description": "Best short, verbatim quote from within this moment. Omitted when the selected video moment has no source-grounded transcript quote." }, "CreateGenerateChaptersJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GenerateChaptersJobParameters" } }, "required": [ "parameters" ] }, "GenerateChaptersJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to generate chapters for." }, "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the output chapter titles. Auto-detected from the transcript if omitted." }, "output_steering": { "$ref": "#/components/schemas/GenerateChaptersOutputSteering" }, "update_asset_chapters": { "type": "boolean", "description": "When true, the generated chapters are written back to the Mux asset as a chapters text track once the job completes, making them deliverable with the asset. Overwrites existing chapters: an asset holds a single chapters track, so any chapters track already on the asset is deleted and replaced — including one in a different language, and one you created yourself. Best-effort — a failed write does not fail the job — so check `asset_updates.chapters` in the job outputs for the outcome." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "update_asset_chapters": true, "output_steering": { "chapter_style": "descriptive", "chapter_granularity": "balanced", "audience": "Developers" } } }, "GenerateChaptersJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateChaptersJob" } }, "required": [ "data" ] }, "GenerateChaptersJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-chapters" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/GenerateChaptersJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/GenerateChaptersJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GenerateChaptersJobOutputs": { "type": "object", "properties": { "chapters": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "number", "minimum": 0, "description": "Chapter start time in seconds. The first chapter always starts at 0." }, "title": { "type": "string", "minLength": 1, "description": "Concise chapter title." } }, "required": [ "start_time", "title" ] }, "minItems": 1, "description": "Generated chapters, ordered by start time." }, "asset_updates": { "$ref": "#/components/schemas/GenerateChaptersAssetUpdateOutcomes" } }, "required": [ "chapters" ], "example": { "chapters": [ { "start_time": 0, "title": "Introduction" } ], "asset_updates": { "chapters": { "status": "created", "track_id": "chaptersabc123def456", "replaced_track_ids": [ "old_chapters_track" ] } } }, "description": "Workflow results. Present when status is completed." }, "GenerateChaptersAssetUpdateOutcomes": { "type": "object", "properties": { "chapters": { "$ref": "#/components/schemas/GenerateChaptersAssetUpdate" } }, "description": "Recorded best-effort chapters track update outcome. A failed update does not fail the analysis job. Omitted when no outcome was recorded." }, "GenerateChaptersAssetUpdate": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/GenerateChaptersAssetUpdateStatus" }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the chapters track created on the asset. Present when status is `created`." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "required": [ "status" ], "description": "What happened when the generated chapters were written back to the Mux asset. Present only when update_asset_chapters was true. When status is `failed` and replaced_track_ids is nonempty, deletion succeeded but replacement creation failed, leaving the asset without a chapters track." }, "GenerateChaptersAssetUpdateStatus": { "type": "string", "enum": [ "created", "failed" ], "description": "Outcome of the chapters track write. `created` means the asset now carries these chapters. `failed` means the write was attempted and errored; the chapters in this response are still valid and can be applied manually." }, "CreateGenerateContextualTextJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GenerateContextualTextJobParameters" } }, "required": [ "parameters" ] }, "GenerateContextualTextJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID whose transcript grounds the generated text." }, "use_shots": { "type": "boolean", "description": "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": { "$ref": "#/components/schemas/GenerateContextualTextOutputSteering" }, "variants": { "$ref": "#/components/schemas/GenerateContextualTextVariants" }, "artifacts": { "$ref": "#/components/schemas/GenerateContextualTextArtifacts" }, "language_code": { "type": "string", "maxLength": 35, "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$", "description": "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": { "type": "string", "maxLength": 35, "pattern": "^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$", "description": "BCP 47 language code for generated text. Defaults to the selected transcript track's language when available." } }, "required": [ "asset_id", "variants", "artifacts" ], "example": { "asset_id": "mux_asset_123abc", "output_steering": { "audience": "Video developers", "voice": "conversational" }, "variants": [ { "key": "product_led", "instructions": "Use a promotional, product-led angle." }, { "key": "insight_led", "instructions": "Use an educational, insight-led angle." } ], "artifacts": [ { "key": "x_post", "channel": "x", "max_length": { "unit": "characters", "value": 280 } }, { "key": "blog_post", "max_length": { "unit": "words", "value": 1200 }, "format": "markdown" } ] } }, "GenerateContextualTextJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateContextualTextJob" } }, "required": [ "data" ] }, "GenerateContextualTextJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-contextual-text" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/GenerateContextualTextJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "$ref": "#/components/schemas/GenerateContextualTextJobOutputs" } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GenerateContextualTextJobOutputs": { "type": "object", "properties": { "variants": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedTextVariant" } } }, "required": [ "variants" ], "example": { "variants": [ { "key": "insight_led", "artifacts": [ { "key": "x_post", "content": "The hard part of repurposing video isn't generating more words. It's keeping every piece grounded in the original story." }, { "key": "blog_post", "content": "# Why video repurposing breaks down after the first draft\n\nMost content workflows treat every deliverable as a separate generation problem. A shared source keeps the whole set grounded." } ] } ] }, "description": "Workflow results. Present when status is 'completed'." }, "GeneratedTextVariant": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GenerateContextualTextKey" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedTextArtifact" } } }, "required": [ "key", "artifacts" ] }, "GeneratedTextArtifact": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/GenerateContextualTextKey" }, "content": { "type": "string", "minLength": 1 } }, "required": [ "key", "content" ] }, "CreateGenerateEngagementInsightsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobParameters" } }, "required": [ "parameters" ] }, "GenerateEngagementInsightsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to analyze engagement for." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc" } }, "GenerateEngagementInsightsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GenerateEngagementInsightsJob" } }, "required": [ "data" ] }, "GenerateEngagementInsightsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-engagement-insights" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/GenerateEngagementInsightsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/GenerateEngagementInsightsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GenerateEngagementInsightsJobOutputs": { "type": "object", "properties": { "moment_insights": { "type": "array", "items": { "$ref": "#/components/schemas/GenerateEngagementInsightsMomentInsight" }, "description": "Per-moment engagement insights for identified hotspots." }, "overall_insight": { "type": "object", "properties": { "summary": { "type": "string", "description": "Summary of overall engagement patterns." }, "trends": { "type": "array", "items": { "type": "string" }, "description": "Key trends identified across the video." } }, "required": [ "summary", "trends" ], "description": "Overall engagement analysis across the video." } }, "required": [ "moment_insights", "overall_insight" ], "example": { "moment_insights": [ { "start_time": 30.123, "end_time": 60.456, "engagement_score": 0.89, "insight": "High engagement during the demo." } ], "overall_insight": { "summary": "Engagement peaks during demonstrations.", "trends": [ "Product demos drive retention" ] } }, "description": "Workflow results. Present when status is completed." }, "GenerateEngagementInsightsMomentInsight": { "type": "object", "properties": { "engagement_score": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized engagement score (0-1)." }, "insight": { "type": "string", "description": "Primary insight explaining the engagement pattern." }, "start_time": { "type": "number", "minimum": 0, "description": "Engagement insight start time in seconds on the original asset timeline. Fractional seconds are supported." }, "end_time": { "type": "number", "minimum": 0, "description": "Engagement insight end time in seconds on the original asset timeline. Fractional seconds are supported." } }, "required": [ "engagement_score", "insight", "start_time", "end_time" ] }, "CreateGeneratePremiumCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobParameters" } }, "required": [ "parameters" ] }, "GeneratePremiumCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to caption." }, "language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code of the audio (e.g. \"en\", \"es\"). A best-effort hint that biases transcription toward this language — it is not verified against the audio and does not guarantee the output language. When supplied, language detection is skipped and the captions are labeled with this code. The language will be auto-detected when omitted; existing tracks are then checked against `replace_existing_tracks` after transcription, so a same-language conflict errors the job at track creation instead of being rejected up front, and a deleting policy only applies when the detection is confident." }, "replace_existing_tracks": { "$ref": "#/components/schemas/GeneratePremiumCaptionsReplaceExistingTracks" }, "track_name": { "type": "string", "minLength": 1, "description": "Custom name for the uploaded Mux text track. Defaults to \"{Language} (Generated)\", e.g. \"English (Generated)\". Mux requires text track names to be unique on an asset." }, "include_speakers": { "type": "boolean", "default": false, "description": "When true, speaker labels are identified and added to each caption cue. Useful for interviews, podcasts, and multi-speaker content." }, "include_words": { "type": "boolean", "default": false, "description": "When true, word-level timestamps are exported as a JSON file accessible via temporary_words_url in the job outputs. The URL expires 7 days after the job completes. Billed at a higher unit rate." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the generated SRT to the Mux asset as a new text track. Defaults to true. When false, no track is created and `replace_existing_tracks` must be `fail`; the generated SRT remains available via `temporary_srt_url`." }, "phrases": { "$ref": "#/components/schemas/GeneratePremiumCaptionsPhrases" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "language_code": "en", "replace_existing_tracks": "fail", "include_speakers": false, "include_words": false, "upload_to_mux": true, "phrases": [ "Mux", "API" ] } }, "GeneratePremiumCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJob" } }, "required": [ "data" ] }, "GeneratePremiumCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "generate-premium-captions" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/GeneratePremiumCaptionsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "GeneratePremiumCaptionsJobOutputs": { "type": "object", "properties": { "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the newly uploaded caption track. Omitted when upload_to_mux is false." }, "language_code": { "type": "string", "minLength": 1, "description": "Resolved language code of the generated captions (may differ from the requested code when auto-detected)." }, "auto_language_confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "The transcription model's confidence in its automatic language detection, from 0 to 1. Always 1 when language_code was supplied in the request, since detection is skipped." }, "temporary_srt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the generated SRT file. Expires 7 days after the job completes." }, "temporary_words_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the word-level timestamp JSON. Present when include_words is true. Expires 7 days after the job completes. Download and store this file for long-term access." }, "detected_language_code": { "type": "string", "minLength": 1, "description": "Language code reported by the transcription model. Only a genuine detection when language_code was omitted from the request; when a language_code hint was supplied, detection is skipped and this echoes the requested language." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "required": [ "language_code" ], "example": { "track_id": "enabc123def456", "language_code": "en", "detected_language_code": "en", "auto_language_confidence": 1, "temporary_srt_url": "https://storage.example.com/captions/en/abc123.srt?token=abc" }, "description": "Workflow results. Present when status is completed." }, "CreateModerateJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/ModerateJobParameters" } }, "required": [ "parameters" ] }, "ModerateJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to moderate." }, "language_code": { "type": "string", "minLength": 1, "description": "Used only for audio-only transcript analysis; ignored for video assets. 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." }, "thresholds": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Score threshold for violent content. Content scoring above this value triggers exceeds_threshold." } }, "default": { "sexual": 0.7, "violence": 0.8 }, "description": "Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}." }, "sampling_interval": { "type": "integer", "minimum": 5, "description": "Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints." }, "max_samples": { "type": "integer", "minimum": 1, "description": "Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned." }, "output_steering": { "$ref": "#/components/schemas/ModerateOutputSteering" }, "on_flagged": { "$ref": "#/components/schemas/ActionOnFlagged" } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "on_flagged": { "action": "delete_playback_ids" } } }, "ModerateJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ModerateJob" } }, "required": [ "data" ] }, "ModerateJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "moderate" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/ModerateJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/ModerateJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "ModerateJobOutputs": { "type": "object", "properties": { "thumbnail_scores": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "number", "minimum": 0, "description": "Time in seconds of the thumbnail within the video. Absent for transcript moderation." }, "sexual": { "type": "number", "minimum": 0, "maximum": 1, "description": "Sexual content score from 0.0 to 1.0." }, "violence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Violence content score from 0.0 to 1.0." } }, "required": [ "sexual", "violence" ] }, "description": "Per-thumbnail moderation scores." }, "max_scores": { "type": "object", "properties": { "sexual": { "type": "number", "minimum": 0, "maximum": 1 }, "violence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "sexual", "violence" ], "description": "Highest scores across all thumbnails for each category." }, "exceeds_threshold": { "type": "boolean", "description": "True if any category's max score exceeds its configured threshold." }, "flagged_action": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "delete_playback_ids" ] }, "deleted_playback_ids": { "type": "array", "items": { "type": "string" }, "description": "Playback IDs that were deleted from the asset because it exceeded the threshold." } }, "required": [ "action", "deleted_playback_ids" ], "description": "Present only when on_flagged was set and exceeds_threshold was true. Records the action taken and which playback IDs were deleted." } }, "required": [ "thumbnail_scores", "max_scores", "exceeds_threshold" ], "example": { "thumbnail_scores": [ { "time": 0, "sexual": 0.01, "violence": 0.02 }, { "time": 30, "sexual": 0.03, "violence": 0.15 }, { "time": 60, "sexual": 0.02, "violence": 0.05 } ], "max_scores": { "sexual": 0.03, "violence": 0.15 }, "exceeds_threshold": false }, "description": "Workflow results. Present when status is completed." }, "CreateSummarizeJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/SummarizeJobParameters" } }, "required": [ "parameters" ] }, "SummarizeJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to summarize." }, "tone": { "type": "string", "enum": [ "neutral", "playful", "professional" ], "description": "Tone for the generated summary. \"neutral\" for straightforward analysis, \"playful\" for witty and conversational, \"professional\" for executive-level reporting." }, "output_steering": { "$ref": "#/components/schemas/SummarizeOutputSteering" }, "title_length": { "type": "integer", "minimum": 1, "description": "Maximum title length in words." }, "description_length": { "type": "integer", "minimum": 1, "description": "Maximum description length in words." }, "tag_count": { "type": "integer", "minimum": 1, "default": 10, "description": "Maximum number of tags to include in the generated output. Defaults to 10." }, "language_code": { "type": "string", "minLength": 1, "description": "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": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the generated summary output (e.g. \"en\", \"fr\", \"ja\"). Auto-detected from the transcript if omitted." }, "update_asset_meta": { "type": "boolean", "description": "When true, the generated title is written to the Mux asset's metadata (asset.meta.title) once the summary completes. Best-effort: a metadata-write failure does not fail the summary." } }, "required": [ "asset_id" ], "example": { "asset_id": "mux_asset_123abc", "tone": "neutral", "tag_count": 10, "update_asset_meta": true, "output_steering": { "scope": { "start_time": 30, "end_time": 180 }, "summary_style": "concise", "audience": "Product marketers", "brand_terms": [ "Mux", "Robots" ] } } }, "SummarizeJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SummarizeJob" } }, "required": [ "data" ] }, "SummarizeJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "summarize" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/SummarizeJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/SummarizeJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "SummarizeJobOutputs": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "Generated title capturing the essence of the video." }, "description": { "type": "string", "minLength": 1, "description": "Generated description of the video content (typically 2-4 sentences)." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Generated keyword tags for the video." }, "asset_updates": { "$ref": "#/components/schemas/SummarizeAssetUpdateOutcomes" } }, "required": [ "title", "description", "tags" ], "example": { "title": "How to Build a Sustainable Garden in Your Backyard", "description": "A step-by-step guide to soil preparation, plant selection, and organic pest control.", "tags": [ "gardening", "sustainability", "backyard" ], "asset_updates": { "title": { "status": "updated" } } }, "description": "Workflow results. Present when status is completed." }, "SummarizeAssetUpdateOutcomes": { "type": "object", "properties": { "title": { "$ref": "#/components/schemas/SummarizeTitleAssetUpdate" } }, "description": "Recorded asset title update outcome. Omitted when no outcome was recorded, including historical jobs." }, "SummarizeTitleAssetUpdate": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "updated", "failed" ], "description": "Outcome of the requested asset title update." } }, "required": [ "status" ] }, "CreateTranslateAudioJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/TranslateAudioJobParameters" } }, "required": [ "parameters" ] }, "TranslateAudioJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video to translate." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the dubbed Mux audio track. Defaults to \"{Language} (Auto-dubbed)\", e.g. \"Spanish (Auto-dubbed)\". Mux requires audio track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to automatically upload the translated audio track to the Mux asset. Defaults to true. Must be false for audio-only assets; the job returns downloadable audio instead." }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateAudioReplaceExistingTracks" }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the target translation language (e.g. \"es\", \"fr\", \"ja\")." } }, "required": [ "asset_id", "output_language_code" ], "example": { "asset_id": "mux_asset_123abc", "output_language_code": "es", "upload_to_mux": true, "replace_existing_tracks": "fail" } }, "TranslateAudioJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslateAudioJob" } }, "required": [ "data" ] }, "TranslateAudioJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "translate-audio" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/TranslateAudioJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/TranslateAudioJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "TranslateAudioJobOutputs": { "type": "object", "properties": { "temporary_audio_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the dubbed audio file. Expires 7 days after the job completes." }, "track_id": { "type": "string", "minLength": 1, "description": "Mux audio track ID, present when upload_to_mux is true." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "example": { "track_id": "esabc123def456", "temporary_audio_url": "https://storage.example.com/dubs/es/audio.m4a?token=abc123", "replaced_track_ids": [ "old_spanish_audio_track" ] }, "description": "Workflow results. Present when status is completed." }, "CreateTranslateCaptionsJobRequest": { "type": "object", "properties": { "passthrough": { "type": "string", "description": "Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems." }, "parameters": { "$ref": "#/components/schemas/TranslateCaptionsJobParameters" } }, "required": [ "parameters" ] }, "TranslateCaptionsJobParameters": { "type": "object", "properties": { "asset_id": { "type": "string", "minLength": 1, "description": "The Mux asset ID of the video whose captions will be translated." }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the source captions. Must identify a ready subtitle track, or the single ready legacy text transcript without subtitle metadata on an audio-only asset. A missing or unready source is rejected." }, "track_name": { "type": "string", "minLength": 1, "description": "Name for the translated Mux text track. Defaults to \"{Language} (Auto-translated)\", e.g. \"Spanish (Auto-translated)\". Mux requires text track names to be unique on an asset, and an existing track with this name is handled according to `replace_existing_tracks`." }, "upload_to_mux": { "type": "boolean", "default": true, "description": "Whether to upload the translated VTT and attach it as a text track on the Mux asset. Defaults to true." }, "never_translate": { "$ref": "#/components/schemas/TranslateCaptionsNeverTranslateTerms" }, "replace_existing_tracks": { "$ref": "#/components/schemas/TranslateCaptionsReplaceExistingTracks" }, "output_language_code": { "type": "string", "minLength": 1, "description": "BCP 47 language code for the translated output (e.g. \"es\", \"ja\"). Unless replace_existing_tracks allows replacement, the asset must not already have a text track for this language." } }, "required": [ "asset_id", "track_id", "output_language_code" ], "example": { "asset_id": "mux_asset_123abc", "track_id": "enabc123def456", "output_language_code": "es", "upload_to_mux": true, "never_translate": [ "Mux" ], "replace_existing_tracks": "fail" } }, "TranslateCaptionsJobResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TranslateCaptionsJob" } }, "required": [ "data" ] }, "TranslateCaptionsJob": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier." }, "passthrough": { "type": "string", "description": "Arbitrary string supplied at creation, returned as-is." }, "units_consumed": { "type": "integer", "minimum": 0, "description": "Number of Mux AI units consumed by this job." }, "directive": { "$ref": "#/components/schemas/JobDirectiveContext" }, "created_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) when the job was created." }, "updated_at": { "type": "integer", "minimum": 0, "description": "Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state)." }, "workflow": { "type": "string", "enum": [ "translate-captions" ], "x-stainless-const": true }, "parameters": { "$ref": "#/components/schemas/TranslateCaptionsJobParameters" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JobError" }, "description": "Error details. Present when status is 'errored'." }, "resources": { "$ref": "#/components/schemas/Resources" }, "outputs": { "allOf": [ { "$ref": "#/components/schemas/TranslateCaptionsJobOutputs" }, { "description": "Workflow results. Present when status is 'completed'." } ] } }, "required": [ "id", "units_consumed", "created_at", "updated_at", "workflow", "parameters", "status" ] }, "TranslateCaptionsJobOutputs": { "type": "object", "properties": { "temporary_vtt_url": { "type": "string", "minLength": 1, "description": "Temporary pre-signed URL to download the translated VTT file, including when upload_to_mux is false. Expires 7 days after the job completes." }, "never_translate_terms_preserved": { "type": "boolean", "description": "Present when never_translate terms were supplied. False when at least one term was not preserved verbatim in the translated captions. Preservation is best-effort: verified, not guaranteed." }, "track_id": { "type": "string", "minLength": 1, "description": "Mux text track ID of the newly created translated captions, distinct from the source parameters.track_id. Present when upload_to_mux is true." }, "replaced_track_ids": { "$ref": "#/components/schemas/ReplacedTrackIds" } }, "example": { "track_id": "esabc123def456", "temporary_vtt_url": "https://storage.example.com/translations/es/captions.vtt?token=abc123", "never_translate_terms_preserved": true }, "description": "Workflow results. Present when status is completed." } } } }```