Video Upload API (V4)

The video upload API allows you to upload videos directly to Twitch. The API enables broadcasters to create tools for creating and managing videos on Twitch. Broadcasters often like to add their personal branding (for intros and outros) and create compilation videos from their streams. With the video upload API, you can enable those experiences and upload the end result directly to Twitch.

Using the API

Video Format

When uploading a video, the API accepts the following format:

  • MP4 file format
  • AAC audio
  • h264 codec
  • Up to 10Mbps bitrate
  • Up to 1080p/60FPS

Rate Limits

There is a rate limit of 5 simultaneous uploads per user, with a maximum of 100 uploads in 24 hours.

Versioning

All API calls must be versioned. The video upload API uses V4 of the Twitch API. You can set the version by sending an Accept header with the value of application/vnd.twitchtv.v4+json.

High Level Steps for Video Upload

  1. Get an authentication token.
  2. Create a video.
  3. Upload video parts.
  4. Complete the video upload.

1. Get an Authentication Token

You need an OAuth token with the channel_editor scope for the channel where the video will live. Once you have the token, you add it to the Authorization header when you create the video.

For information about getting OAuth access tokens, see the Authentication guide.

2. Create a Video

You create a video with a POST request to the videos endpoint.

The response contains important information for use in future API calls. In particular, the upload object contains the URL where you will send video parts and the token you will use to send them.

Upload tokens expire after 1 day. If you lose the token or it expires, you must start a new upload and get a new token.

Authentication

Required scope: channel_editor

URL

POST https://api.twitch.tv/kraken/videos

Required Parameters in the Request Body

Name Type Description
channel_name string Name of the channel where the video will live.
title string Descriptive title for the video.

Example Request

This creates a video entitled “Test video” in the dallas channel.

1
2
3
4
5
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-H 'Authorization: OAuth m6b89kpgfot0943t7v39cps0t3d2xd' \
-H 'Content-Type: application/json' \
-d '{"channel_name": "dallas", "title": "Test video", "description": "This is a test video.", "tags": "test,video,upload"}' \
-X POST 'https://api.twitch.tv/kraken/videos'

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
    "upload": {
        "token": "r4fUEZjH.Kup7H5nDLHoz7bfyj2bejCggJSHgTVkpZy9UOkdVfMf1EQ10QyuCHxX_TAbt7YV92BZ7EnwHAqDWR8wmsOx_krRnfJdFssyMsngqoG4FuGqyP0VWjoWs1JWIkGnd9DN8Ty.mscFq5Wgrd--",
        "url": "https://uploads.twitch.tv/upload/120209992"
    },
    "video": {
        "_id": "v120209992",
        "_links": {
            "channel": "https://api.twitch.tv/kraken/channels/dallas",
            "self": "https://api.twitch.tv/kraken/videos/v120209992"
        },
        "broadcast_id": 1,
        "broadcast_type": "upload",
        "channel": {
            "display_name": "dallas",
            "name": "dallas"
        },
        "created_at": "2017-02-06T20:44:39Z",
        "description": "This is a test video.",
        "fps": {},
        "game": null,
        "language": "en",
        "length": 0,
        "paywalled": false,
        "preview": {
            "large": "https://vod-secure.twitch.tv/_404/404_processing_640x360.png",
            "medium": "https://vod-secure.twitch.tv/_404/404_processing_320x180.png",
            "small": "https://vod-secure.twitch.tv/_404/404_processing_80x45.png",
            "template": "https://vod-secure.twitch.tv/_404/404_processing_{width}x{height}.png"
        },
        "published_at": null,
        "recorded_at": "2017-02-06T20:44:39Z",
        "resolutions": {},
        "status": "created",
        "tag_list": "",
        "thumbnails": {
            "large": [],
            "medium": [],
            "small": [],
            "template": []
        },
        "title": "Test video",
        "url": "https://www.twitch.tv/videos/120209992",
        "viewable": "public",
        "viewable_at": null,
        "views": 0
    }
}

Status Codes for Creating a Video

Code Description
200 Success. The video was created successfully.
400 Invalid Channel. The specified channel was not found.
401 Unauthorized. The specified OAuth token does not have the correct scope or is invalid.
500 Internal Server Error. The server reported an error but can be retried.

3. Upload Video Parts

A video is uploaded in parts; each part is uploaded with a PUT request.

You must include the length of the content in the content-length header. The body of the request is a byte[] that contains the video data.

Each video part except the last part must be at least 5MB and at most 25MB. The total of all parts cannot exceed 10GB.

Authentication

None

URL

PUT https://uploads.twitch.tv/upload/<video ID>?part=N&upload_token=XXXXXX

Required Query-String Parameters

Name Type Description
part integer Where in the sequence this video part will be included in the completed video. The value of this is 1-based.
upload_token integer Upload token from the create response (in Step 2).

Example Request

This uploads the video created in the prior step.

1
2
3
4
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-H 'Content-Length: 25000000' \
--data-binary "@test.mp4" \
-X PUT 'https://uploads.twitch.tv/upload/120209992?part=1&upload_token=r4fUEZjH.Kup7H5nDLHoz7bfyj2bejCggJSHgTVkpZy9UOkdVfMf1EQ10QyuCHxX_TAbt7YV92BZ7EnwHAqDWR8wmsOx_krRnfJdFssyMsngqoG4FuGqyP0VWjoWs1JWIkGnd9DN8Ty.mscFq5Wgrd--'

Example Response

1
200 OK

Status Codes for Uploading a Video Part

Code Description
200 Success. The video-part upload was completed successfully.
400 Upload Already Completed. The specified video is already a completed upload.
400 Upload Failed. The video-part upload failed.
401 Invalid Upload Token. The specified upload token is invalid.
404 Invalid Video Id. The specified video ID is invalid.
411 Content Length Required. The content-length header is missing.
500 Internal Server Error. The server reported an error but can be retried.

4. Complete the Video Upload

The request to complete the upload must include the upload token in the upload_token query-string parameter.

Authentication

None

URL

POST https://uploads.twitch.tv/upload/<video ID>/complete?upload_token=XXXXXX

Required Query-String Parameter

Name Type Description
upload_token integer Upload token from the create response (in Step 2).

Example Request

This completes the upload of video 120209992.

1
2
curl -H 'Accept: application/vnd.twitchtv.v4+json' \
-X POST 'https://uploads.twitch.tv/upload/120209992/complete?upload_token=r4fUEZjH.Kup7H5nDLHoz7bfyj2bejCggJSHgTVkpZy9UOkdVfMf1EQ10QyuCHxX_TAbt7YV92BZ7EnwHAqDWR8wmsOx_krRnfJdFssyMsngqoG4FuGqyP0VWjoWs1JWIkGnd9DN8Ty.mscFq5Wgrd--'

Example Response

1
200 OK

Status Codes for Completing a Video Upload

Code Description
200 Success. The video upload was completed successfully.
400 Invalid Upload Token. The specified upload token is invalid.
400 Invalid Video Id. The specified video ID is invalid.
400 Missing Parts. The video upload is missing parts.
500 Internal Server Error. The server reported an error but can be retried.