---
updatedAt: 2026-04-20T20:26:21.000Z
agentTools:
  projectIndex: https://docs.wistia.com/llms.txt
---

# Create Captions

Adds captions to a specified media by providing an SRT file or its contents directly.

## Requires api token with one of the following permissions
```
Read, update & delete anything
```

Tokens with the "Act with a team member's permissions" permission
(`all:delegate_to_contact_permissions` scope) can also be used. Requests
made with such a token are authorized using the permissions of the
contact assigned to the token.

An [expiring access token](https://docs.wistia.com/reference/post_expiring-token)
created with the `all:delegate_to_contact_permissions` scope and an
authorization granting the `create-transcripts` permission on this media can
also be used.


# OpenAPI definition

````json
{
  "openapi": "3.1.1",
  "info": {
    "title": "Data API",
    "description": "Wistia Data API",
    "version": "2026.09.0"
  },
  "servers": [
    {
      "url": "https://api.wistia.com/modern"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Captions"
    }
  ],
  "paths": {
    "/medias/{mediaHashedId}/captions": {
      "post": {
        "summary": "Create Captions",
        "x-speakeasy-group": "captions",
        "x-speakeasy-name-override": "create",
        "description": "Adds captions to a specified media by providing an SRT file or its contents directly.\n\n## Requires api token with one of the following permissions\n```\nRead, update & delete anything\n```\n\nTokens with the \"Act with a team member's permissions\" permission\n(`all:delegate_to_contact_permissions` scope) can also be used. Requests\nmade with such a token are authorized using the permissions of the\ncontact assigned to the token.\n\nAn [expiring access token](https://docs.wistia.com/reference/post_expiring-token)\ncreated with the `all:delegate_to_contact_permissions` scope and an\nauthorization granting the `create-transcripts` permission on this media can\nalso be used.\n",
        "parameters": [
          {
            "name": "mediaHashedId",
            "in": "path",
            "description": "The hashed ID of the media for which captions are to be added.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Wistia-API-Version",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "default": "2026-09"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "unevaluatedProperties": false,
                "type": "object",
                "properties": {
                  "caption_file": {
                    "description": "Either an attached SRT file or a string parameter with the contents of an SRT file.",
                    "type": "string"
                  },
                  "language": {
                    "description": "An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.",
                    "type": "string"
                  }
                },
                "required": [
                  "caption_file"
                ]
              }
            },
            "multipart/form-data": {
              "schema": {
                "unevaluatedProperties": false,
                "type": "object",
                "properties": {
                  "caption_file": {
                    "description": "Either an attached SRT file or a string parameter with the contents of an SRT file.",
                    "type": "string",
                    "format": "binary"
                  },
                  "language": {
                    "description": "An optional parameter that denotes which language this file represents. Should conform to ISO-639–2. If left unspecified, the language code will be detected automatically.",
                    "type": "string"
                  }
                },
                "required": [
                  "caption_file"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Captions added successfully"
          },
          "400": {
            "description": "Captions already exist for this media"
          },
          "401": {
            "description": "Unauthorized, invalid or missing token",
            "content": {
              "application/json": {
                "schema": {
                  "unevaluatedProperties": false,
                  "type": "object",
                  "properties": {
                    "code": {
                      "description": "A machine-readable identifier for the specific authorization failure.",
                      "type": "string",
                      "enum": [
                        "unauthorized_credentials",
                        "account_inactive",
                        "unauthorized_scope",
                        "unauthorized_params"
                      ]
                    },
                    "error": {
                      "type": "string",
                      "examples": [
                        "Invalid credentials."
                      ]
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden, token is valid but account does not have access to feature",
            "content": {
              "application/json": {
                "schema": {
                  "unevaluatedProperties": false,
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "Webinars are not available on your current plan"
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Media not found"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "unevaluatedProperties": false,
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "examples": [
                        "Internal server error"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Captions"
        ],
        "x-readme": {
          "code-samples": [
            {
              "name": "Typescript (SDK)",
              "language": "javascript",
              "code": "import { Wistia } from \"@wistia/wistia-api-client\";\n\nconst wistia = new Wistia({\n  bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n  await wistia.captions.create({\n    mediaHashedId: \"<id>\",\n    requestBody: {\n      captionFile: \"\" // Populate with string from file, for example example.file,\n    },\n  });\n\n\n}\n\nrun();"
            },
            {
              "name": "Typescript (SDK)",
              "language": "javascript",
              "code": "import { Wistia } from \"@wistia/wistia-api-client\";\nimport { openAsBlob } from \"node:fs\";\n\nconst wistia = new Wistia({\n  bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n  await wistia.captions.createMultipart({\n    mediaHashedId: \"<id>\",\n    requestBody: {\n      captionFile: await openAsBlob(\"example.file\"),\n    },\n  });\n\n\n}\n\nrun();"
            }
          ]
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "x-readme": {
    "samples-languages": [
      "javascript",
      "shell",
      "node",
      "python",
      "ruby"
    ]
  }
}
````