The OpenTok REST API allows you to:
You can obtain a new session by submitting a POST request.
Note: You can also create a session ID using the create_session() method of the OpenTok server-side libraries.
https://api.opentok.com/hl/session/create
In production, API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and partner secret concatenated with a colon:
X-TB-PARTNER-AUTH: <api_key>:<partner_secret>
In other words, the POST request will have the following form:
POST /session/create HTTP/1.1 host: https://api.opentok.com/hl X-TB-PARTNER-AUTH: api_key:partner_secret
To create a peer-to-peer session, include the following form data: p2p.preference=enabled.
(By default, sessions are multi-party, not peer-to-peer.)
To call the function from the command line, you could issue a command like the following:
export TB_url=https://api.opentok.com/hl/session/create headerstr="X-TB-PARTNER-AUTH: API_KEY:API_SECRET" curl -X POST -H "$headerstr" $TB_url
Replace the API_KEY and API_SECRET with the API key and
partner secret provided to you when you signed up for an OpenTok account.
The location setting is optional, and generally you should not include it. This setting is an IP address that TokBox will use to situate the session in its global network. If no location hint is passed in (which is recommended), the session uses a media server based on the location of the first client connecting to the session. Pass a location hint in only if you know the general geographic region (and a representative IP address) and you think the first client connecting may not be in that region. If you need to specify an IP address, replace IP_ADDRESS with an IP address that is representative of the geographical location for the session.
The response is XML data of the following form:
<sessions>
<Session>
<session_id>SESSION_IDlt;/session_id>
<partner_id>API_KEY</partner_id>
<create_dt>DATE</create_dt>
<session_status></session_status>
</Session>
</sessions>
You can download an OpenTok archive manifest by submitting a POST request.
The archive manifest contains video IDs for each recorded stream in the archive. Use these video IDs to download archive videos.
https://api.opentok.com/hl/archive/getmanifest/archive_ID
Where archive_ID is the archive ID of the archive you are interested in.
(You should save a record of the archive ID when you create an archive using the OpenTok JavaScript API.
For example, the Session object or dispatches an archiveCreated event when an archive
is created. For stand-alone archives, the Recorder object dispatches an archiveSaved event when
the archive is saved. See the Session.createArchive() method and the
Recorder class.)
Include the token string as an x-tb-token-auth variable in the HTTP header data.
Use a token that has been assigned the role of moderator. See the generate_token() method of the OpenTok server-side libraries.
The result of the API call is an archive manifest file. This is an XML file that describes the videos included in the
archive. (A per-session archive may include multiple videos, whereas a per-stream and individual archives each include only one video.)
The videos are defined in video sub-elements of the resources element. For example, the following manifest XML
defines an archive that includes one video, which has the ID "125f0b49-e452-4b61-ade5-2f4589ade4cb" and the stream name "Bob":
<manifest version="0.1"
archiveid="340ded4d-a587-4ca0-b92a-ef86b6997fc7"
title="archive1318034901141">
<resources>
<video id="125f0b49-e452-4b61-ade5-2f4589ade4cb" length="8687" name="Bob" />
</resources>
<timeline>
<event type=”PLAY” id="125f0b49-e452-4b61-ade5-2f4589ade4cb" offset="0" />
</timeline>
</manifest>
Note: For archives created prior to OpenTok v0.91.48, the stream name in the archive manifest is always set to an empty string.
You can obtain video IDs for videos in an archive from the archive manifest file. You can then use a video ID in this REST API call to get the download URL of the file.
https://api.opentok.com/hl/archive/url/archive_ID/video_id
Where archive_ID is the archive ID of the archive, and video_id is the video ID (which you obtained from the
archive manifest XML data). Include the token string as an x-tb-token-auth variable in the HTTP header data.
Note: You can use different tokens to download the archive manifest and to download the FLV file. However each token must be created with the API key that was used to create the archive, and each token must include the moderator role.
You must specify a token string or a combination of an OpenTok API key and partner secret:
x-tb-token-auth variable in the HTTP header data.
Use a token that has been assigned the role of moderator. See the generate_token() method of the OpenTok server-side libraries.
X-TB-PARTNER-AUTH: <api_key>:<partner_secret>
In other words, the POST request will have the following form:
POST /hl/archive/url/archive_ID/video_id HTTP/1.1 host: https://api.opentok.com/hl X-TB-PARTNER-AUTH: api_key/partner_secret
The result of the API call is the URL of the video file. OpenTok archive video files are FLV files.
You can delete archives that were created using your API key.
https://api.opentok.com/hl/archive/delete/archive_ID
Where archive_ID is the archive ID of the archive you want to delete.
(You should save a record of the archive ID when you create an
archive using the OpenTok JavaScript API. For example, the Session object or dispatches an archiveCreated event
when an archive is created. For stand-alone archives, the Recorder object dispatches an archiveSaved event when
the archive is saved. See the Session.createArchive() method and the
Recorder class.)
Include the token string as an x-tb-token-auth variable in the HTTP header data.
Use a token that has been assigned the role of moderator. See the generate_token() method.
The HTTP response status code for the call will be one of the following:
| HTTP response status code | Description |
|---|---|
| 200 | Success, the archive is deleted. |
| 404 |
Archive not found, returned in the following cases:
|
| 500 | Error on the TokBox server. Perhaps the service is unavailable. |
This API lets you generate a single-file MP4 file displaying the streams of a multi-stream archive.
Once the MP4 file is generated, you can use the REST API for downloading a composite video of a multi-stream archive.
This API supports generating videos of multi-stream archives that contain two to four streams. Attempting to generate a video of an archive that contains more streams will fail silently.
https://api.opentok.com/hl/archive/[archive_id]/stitch
Where [archive_id] is the archive ID of the archive you want to use to generate a video compilation.
API calls must be authenticated using a custom HTTP header: X-TB-PARTNER-AUTH. Send your API key and partner secret concatenated with a colon:
X-TB-PARTNER-AUTH: <api_key>:<partner_secret>
In other words, the POST request will have the following form:
POST /archive/[archive_id]/stitch HTTP/1.1 host: https://api.opentok.com/hl X-TB-PARTNER-AUTH: api_key/partner_secret
To call the function from the command line, you could issue a command like the following:
export TB_url=https://api.opentok.com/hl/archive/[archive_id]/stitch postdata="api_key=api_key&location=IP_ADDRESS" headerstr="X-TB-PARTNER-AUTH: API_KEY:API_SECRET" curl -d $postdata -H $headerstr $TB_url
Optionally, you can pass in the endpoint parameter to subscribe a callback for notifications when the
command has finished. You can define an end-point to be a URL using either the HTTP or HTTPS protocol.
The raw data of the response is a JSON-encoded message of the following form:
{
"error":"An error message (if there is one)",
"archiveId":"The archive ID (if there is one)",
"url": "The URL of the MP4 file (if there is one)"
}
The JSON object will either have a non-empty error string (with archiveId and url being empty strings) or an empty error string with archiveId and url being non-empty strings.
If an end-point is passed in, the call to the API results in a POST to that callback.
If a developer calls the API multiple times while the same archive is being processed, the POST result goes to the last end-point registered.
If a call fails for whatever reason it will not be attempted again.
| 201 CREATED | Returned when the resulting MP4 file has been created. The returned value is the URL of the resulting MP4 file. |
| 202 ACCEPTED | We accepted the request and it is made ready for processing. |
| 403 FORBIDDEN | Returned in case of invalid credentials. |
| 404 NOT_FOUND | Returned if the archive does not exist. |
| 500 SERVER_ERROR | In case of some internal failure. This can result from attempting to create a video of an archive that has more than four streams. Also, this can result if one of the archive videos is corrupt, in which case the return error message includes a link to a log that contains more information. |
For a video creation that ends in success, the web call returns the status 202 (in progress) until it returns 201 (complete). When you get the 201 response, you can get the URL of the download video using download composite archive REST API.
This is the basic syntax (where API_KEY is you API key, API_SECRET is your API secret, and ARCHIVE_ID is the archive ID):
headerstr="X-TB-PARTNER-AUTH:API_KEY:API_SECRET" resturl="https://api.opentok.com/hl/archive/ARCHIVE_ID/stitch" curl -d "" -H $headerstr $resturl
This example adds an end-point URL:
headerstr="X-TB-PARTNER-AUTH:API_KEY:API_SECRET" resturl="https://api.opentok.com/hl/archive/ARCHIVE_ID/stitch?endpoint=YOUR_SERVER_URL" curl -d -H $headerstr $resturl
Replace ARCHIVE_ID with the archive ID and YOUR_SERVER_URL with the server URL.
Once you have generated a composite video of a multi-stream archive, you can download it using this API.
Archives video compilations are MP4 files.
https://api.opentok.com/hl/archive/archive_id/stitch
Where archive_id is the archive ID of the archive.
Include the token string as an x-tb-token-auth variable in the HTTP header data.
Use a token that has been assigned the role of moderator. See the generate_token() method.
| 200 OK | The API returns the URL of the MP4 file. |
| 403 FORBIDDEN | Returned in case of invalid credentials. |
| 404 NOT_FOUND | Returned if the archive does not exist or the video has not yet been created. |
The following call returns the URL of the MP4 file:
headerstr="X-TB-TOKEN-AUTH:TOKEN_STRING" resturl="https://api.opentok.com/hl/archive/ARCHIVE_ID/stitch/" curl -H $headerstr $resturl xargs curl
Replace ARCHIVE_ID with the archive ID.