Skip to content
  • There are no suggestions because the search field is empty.

How to Get Caption and Dubbed Pages for Services Using the API

This guide will walk you through using the SyncWords Live API to generate caption pages, iframe widgets, and QR codes for your Services.

Prerequisites

Before you begin, you'll need:

  • Your Service ID (found in your Service settings)

  • Your API keys (public key and private key)

  • Access to the SyncWords Live API Documentation 2 (Organization settings)

IMPORTANT: Only account Owners and Admins can access and adjust the Organization Settings pages

Step 1: Set up your SyncWords Service

Create or configure your SyncWords Service.

Please see Step 1: General Settings - How do I create a Service using the new UI? for more information.

Step 2: Open SyncWords Live API Documentation (v2).

From your SyncWords Live page, click on API as shown to open the API section under your Organization settings
 
  

NOTE: Only account Owners and Admins have access to the API page.

This will take you to the API section under your Organization settings. Click on SyncWords Live API Documentation (v2) to open the API page.
 
 
 
 

Step 3: Authenticate with the API

Authentication is required before using any API functions and typically lasts about 30 minutes.

If your session expires or you receive a 401 error, simply re-authenticate before continuing.

Authentication Steps

  1.  On the SyncWords API page, click on Auth (Manage Authentication) to create a token.

  2. Click on POST: Token Create to expand (Create a bearer token)

  3. For the Request Body to be editable, click Try it out

  4. Enter your credentials:
    Username = API_PUBLIC_KEY, Password = API_SECRET_KEY
    Use these credentials under the API section (Organization settings)

  5.  Paste them in this section, and click Execute

  6.  Confirm you see: "You have been successfully authenticated." with a 200 server response code



NOTE: If you receive a "401 - Error: Unauthorized" server response at any point during the process, return to this step and re-authenticate before retrying.

IMPORTANT: If you close or navigate away from the API page, you might need to authenticate again 

 

Step 4: Configure Widget Output Settings to enable the Required Output URLs

Once authenticated, you can configure your caption pages and widgets.

  1. On the SyncWords API page, click on Widget Output Settings.

  2. Click on Patch – Update Widget Outputs Settings

  3. For the Request Body to be editable, click Try it out

  4.  Enter your SyncWords Service ID

  5. Here are all the values you can configure. Make sure you are on Edit Value.

  6. Configure the below values as required.

  7. Once you have updated your settings, click Execute.
  8.  Under Server response, confirm that the status code is 200.


Step 5: Retrieve the Output URLs

After successfully executing, the response will include your enabled URLs in the enabled_urls section.

  1. In the Server Response section, find the enabledUrls or enabledEmbeds fields. The URLs will appear in the following format:



  2. Copy the relevant URL(s) for the Captions page, the Dubs page, or the iframe embed as required.

NOTE: If using an iframe embed script, remove any unnecessary backslashes from the script before use. The raw response may include escape characters that are not needed in the final embed code.

IMPORTANT:

  1. Only enabled pages will have active URLs
  2. Disabled pages will return a 404 error


Step 6: Retrieve URLs/iFrame for the Captions/Dubs Pages 

Once the pages/widgets you require from your Service are enabled they remain available until disabled. You can retrieve them at any time.

Retrieval Steps

  1. On the SyncWords API page, click on Widget Output Settings - Manage Widget Outputs Settings
  2. Expand the GET /services/{id}/widget endpoint (Get Widget Outputs Settings for a specific service)
  3. Click Try it out
  4. Enter your Service ID in the id field
  5. Click Execute

  6. In the Server Response body, you should see the URLs and iframes that have already been configured for that Service

TIP: This is useful when you need to retrieve URLs for sharing with stakeholders or embedding in different locations without having to reconfigure your widget settings.


Step 7: Apply a Widget Theme (Optional)

If you want to customize an iframe, you can do that by choosing it - with Widget theme from the dropdown.

Create your widget theme in your SyncWords account if you have not already done so. This can be done on your Organization settings.



Apply the theme to your Service

  1. In the Widget settings update section, select the Update Widget Outputs Settings With Widget Theme.


  2. Update the widgetTheme Id field with your theme number.
    For example: "widgetThemeId": 42
  3. If you have already created the widget Theme, you can get the widget Theme Id from your Organization settings.
  4. Click on the 3 dots and then click edit on the Widget theme created.


  5. This will take you to the page where you can copy the Widget theme ID


  6. Click Execute and confirm a 200 server response code.

NOTE: If you don't specify a theme, the default theme set up in your account will apply.


Step 8: Retrieve a QR Code for the Captions Page (Optional)

To generate a QR code for your caption page:

On the SyncWords API page, click on QR Codes - Manage QR Codes for services, expand the GET endpoint.

Retrieve the QR code:

  1. Click Try it out.
  2. Paste your Service ID into the id field.
  3. Click Execute.
  4. From the server response, copy the URL for the PNG or SVG file as required.

  5. Paste the URL into a browser to view and download the QR code.

NOTE: A QR code is only available via the API for the Captions URL. If you require a QR code for the Dubs URL, or a combined QR code containing both URLs, you will need to use a 3rd party QR code generator.


Step 9: Upload a Logo to a Service (Optional)

You can add a custom logo to your caption pages using two methods:

Method 1: Default Logo (Automatic)

Set a default logo in your Organization settings. This logo will automatically apply to all services in your account.


Method 2: Service-Specific Logo (API)

Upload a logo for a specific Service using the API.

  1. On the SyncWords API page, click on Service Logo - Manage Service logos, expand the POST endpoint.

  2. Upload the logo:
  • Click Try it out.
  • Paste your Service ID into the id field.
  • Upload your logo image to the Logo file to upload field.
  • Click Execute and confirm a successful response.


Important Reminders

Critical: Settings Reset on Page Refresh

  • When you refresh the API page or navigate away and return, all field values reset to empty.

This means:

  • You must re-enter ALL settings you want to keep, not just the ones you're changing

  • Executing with empty fields will reset those values to default

  • Always include the complete configuration when making updates

 

Additional Features

Caption History Duration: Controls how long captions remain visible on the page.

Example: Set to 1 hour

Behavior:

  • Users who open the page at the start see all captions (unless they refresh)
  • If a user refreshes 2.5 hours into a 3-hour event, they'll only see the last 1 hour of captions
  •  Older captions automatically disappear from view


Caption Delay: Useful when embedding captions in a stream that has latency.