search shadow

Live Ordering API Follow

Overview

Verbit’s Live Ordering API Version allows programmatic access to Verbit’s Live end-to-end transcription and captioning service. Live orders are offered for all 3 service levels: Elite (handled end-to-end by expert captioners), Pro (adapted ai supported by human transcribers, and Automatic (automatic transcription based on adapted ai). Transcripts and closed captions for video and audio can be easily integrated into customer’s systems, enhancing user experience, and increasing accessibility requirements.

Contents

  1. Authentication Flow
    1. Generating API Key
    2. Generating a JWT using the API Key
    3. Authorize using the JWT
  2. Order Delivery Inputs
  3. Other Features and Functions
    1. Main API URL
  4. How to Receive Product Details
  5. How to Create a New Order
  6. Contact Email

Authentication Flow

To use the services of Verbit via API, authentication is required using JSON Web Token (JWT) authentication. This authentication method requires the customer to generate a JWT using a unique API key which identifies the customer.

Authentication is performed using the Verbit authentication-service API.

JWT Authentication is a multi-step process which consists of:

  • Copying a unique customer API key from the authentication UI - The API key does not expire (unless a new one is generated) and can always be used to generate a JWT.
  • Generating a JWT using the API key - - The API key can be copied from the previous step and used to generate the JWT via the Authentication API.
  • Authorize using the JWT - Once the JWT is generated, it can be copied and pasted into the authorization header of each endpoint before making a request.

Generating API Key

To submit any type of job to Verbit via API, the customer is required to generate a User Token API key. .

To generate an API Key:

  1. Log into Verbit.
  2. Click on your account name in the top-right menu bar.
  3. Select My account.
  4. Click Generate Key.

Important: Make sure you safely copy and store your API Key. The Key will not appear again.

live-ordering-api-img-01.png

Generating a JWT using the API Key

By using the API key copied from the authentication UI, a JSON web token (JWT) can be generated by passing the API key (api_key) into the request body.

Sample authentication:

live-ordering-api-img-02.png

Authorize using the JWT

Copy and paste the token into the authorization header of each endpoint before making a request.

Example:

Authorization: Bearer <token>

NOTE: For more detailed information about API Authentication, refer to our online documentation on this link: https://app.swaggerhub.com/apis-docs/Verbit/authentication-service/.

Order Delivery Inputs

The Ordering API can receive media using the various input methods:

  • Websocket – you will receive the WebSocket URL in the response’s “inputs” / “output” field. When establishing the connection to the Speech Recognition service, you should authenticate the same way of using any API call.
  • RTMP
    • RTMP_Push – you will receive an RTMP Stream URL and Key in the response’s “inputs” field. The media should be pushed to this address, for the speech recognition service to consume it.
    • RTMP_Pull – you will need to provide an RTMP Stream URL and Key from which the media should be consumed by the speech recognition service.
  • Zoom – requires you to provide Verbit with a Zoom meeting URL and receive captions directly to Zoom app.

Other Features and Functions

The Ordering API can also support these features and functions:

  • Return details of single/multiple orders in the Verbit system.
  • Create a new order (including creating events and defining their schedules).
  • Update single/multiple existing order information.
  • Update the status of an existing order.
  • Create a download request for the captioning or transcription files of a completed order.
  • Return details of an existing download request.
  • Return the status of an existing download request.
  • Return the download URL of an existing download that is ready to download.
  • Return customer details (including information about the products and services they are using).

Main API URL

Verbit’s main API URL is  https://orders.verbit.co/api/v2.

NOTE: For more detailed information on how to use Verbit Live Ordering API, visit our online API documentation here: https://app.swaggerhub.com/apis/Verbit/ordering/2.0.2 

How to Receive Product Details

GET https://orders.verbit.co/api/v2/customer.

Example of Customer Details including Products:

The customer will receive a response containing a list of the products definition and id (id is static), which can be used for executing order creation calls.

{ 
  "customer": { 
    "id": "2ed29f8e-e2cd-474e-a25f-10c12359902e", 
    "platform_id": 43706, 
    "name": "Customer name", 
    "products": [ 
      { 
        "id": "36c3e6cf-aae3-4c21-a440-7bed2a017555", 
        "name": "Live - Transcripts & Captions - Auto - English - 1 minute notice", 
        "type": "captions", 
        "tier": "automatic", 
        "service_type": "live", 
        "source_language": "en-US", 
        "target_language": "en-US", 
        "turn_around_time_hours": 0, 
        "notice_period_hours": 0 
      }, 
      { 
        "id": "22a31502-ea0a-4e59-b504-7eb7c1f252c3", 
        "name": "Live - Transcripts & Captions - Pro - English - 24 hr notice", 
        "type": "captions", 
        "tier": "professional", 
        "service_type": "live", 
        "source_language": "en-US", 
        "target_language": "en-US", 
        "turn_around_time_hours": 0, 
        "notice_period_hours": 24 
      }, 
      { 
        "id": "40891daa-5314-4ca8-a8e8-3a6eaf5e6890", 
        "name": "Live - Transcripts & Captions - Pro - English - 48 hr notice", 
        "type": "captions", 
        "tier": "professional", 
        "service_type": "live", 
        "source_language": "en-US", 
        "target_language": "en-US", 
        "turn_around_time_hours": 0, 
        "notice_period_hours": 48 
      }, 
      { 
        "id": "d132b8ef-dd5c-401c-b770-14647ba64048", 
        "name": "Live - Transcripts and Captions - Elite - English - 48 hr notice", 
        "type": "captions", 
        "tier": "elite", 
        "service_type": "live", 
        "source_language": "en-US", 
        "target_language": "en-US", 
        "turn_around_time_hours": 0, 
        "notice_period_hours": 48 
      } 
    ], 
    "organization_id": "81190fa2-93c3-4e67-867a-7668cd8eac49", 
    "upload_limit_attachments": 5242880, 
    "upload_limit_media": null,     
  } 
} 

How to Create a New Order

The Create Order endpoint creates a new order in the Verbit system.

The following details can be specified in the request body:

  • Order Name
  • Client Transaction ID (unique transaction id from customer’s backend system which will be assigned to an order and used for tracing)
  • Order Input Details
    • Order Input Language: Source media file for the planned Live session.
      Example: en-US Language code.
      Format should be RFC 5646 Language code
    • Order glossary terms: Glossary, up to 400 words.
      Any words added to the glossary that might appear in the audio highly affect the quality of the output.
    • Order schedule: Time of the scheduled Live event.
      start_at: Format ISO8601 
      example: “2023-07-16T19:00:00Z”
      timezone: timezone of the event
      max_duration: Max session duration in seconds
    • Input type (websocket, rtmp_push, rtmp_pull, web_url)
      In the case of web_url, there is an additional field specifying url_type, for example “zoom”. For rtmp pull, the customer must provide the rtmp url and the string key.
  • Order output details:
    • Product ID
    • Order delivery method settings (websocket, rtmp_push, zoom)

Example of Create Order Request

POST https://orders/verbit.co/api/v2/order
{ 
  "name": "Live Show", 
  "client_transaction_id": "test-websocket-1232s23", 
  "input": { 
    "language": "en-US", 
    "glossary": [ 
      "John", 
      "Marry" 
    ], 
    "schedule": { 
      "start_at": "2023-02-17T08:24:47.639715+00:00", 
      "max_duration": 28800 
    }, 
    "type": "websocket" 
  }, 
  "output": [ 
    { 
      "product": { 
        "id": "36c3e6cf-aae3-4c21-a440-7bed2a017555" 
      }, 
      "delivery": [ 
        { 
          "type": "websocket" 
        } 
      ] 
    } 
  ] 
} 

Example of Create Order Response

{ 
  "order": { 
    "id": "7d1f8841-bcf5-4ca7-933e-26cc833b1a4f", 
    "short_id": "7904636", 
    "name": "Live Show", 
    "client_transaction_id": "test-websocket-1232s23", 
    "status": { 
      "name": "created", 
      "message": "Order '7d1f8841-bcf5-4ca7-933e-26cc833b1a4f' is created" 
    } 
    "last_updated_at": "2023-02-14T14:03:34.158787", 
    "input": { 
      "language": "en-US", 
      "glossary": [ 
        "John", 
        "Marry" 
      ], 
      "schedule": { 
        "recurrence": false, 
        "start_at": "2023-02-17T08:24:47.639715+00:00", 
        "max_duration": 28800 
      }, 
      "type": "websocket", 
      "connection_params": { 
        "url": "wss://speech-qa.verbit.co/ws?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJjdXN0b21lcl9pZCI6MTcwNiwiY3VzdG9tZXJfbmFtZSI6Ik9yZGVyaW5nX3Rlc3QiLCJvcmRlcl9pZCI6IjdkMWY4ODQxLWJjZjUtNGNhNy05MzNlLTI2Y2M4MzNiMWE0ZiIsInZhbGlkX2Zyb21fdHMiOjE2NzY2MjAxMjcuNjM5NzE1LCJ2YWxpZF91bnRpbF90cyI6MTY3NjY2NTQ4Ny42Mzk3MTV9.oqaLEWBqPgzCUQBpYhXG2zlCu1zbcDygEQdXE8hnvXH6_UOdb0Ojv2wVJ1OnqLh0a41nkv1qFiH1heJsU29MRtiYa9D9JlAJc3wqKIqCLQ85jhP7oaruE-5j6WoMIQK9TF0hzhdSTlZtrjAeH0CgPAU0A_l4mRaeVQtbt97cRj4wsGv1YD6NUmkOOtMWWTOI6Iqwibz0zAV5H_Q5PqDg02R7IFxqgeXfpQuseDYGL1hGh_8uhDPyfW_kxduee3R_Z2ISrpOdu6BkywlXAUbqWhvhIV_LM4A7Bqp1FD1HGI1DFLyYroReleQL1bNs4FYUJBxniJeSWr3w" 
      } 
    }, 
    "output": [ 
      { 
        "product": { 
          "id": "36c3e6cf-aae3-4c21-a440-7bed2a017555", 
          "type": "captions" 
        }, 
        "delivery": [ 
          { 
            "type": "websocket", 
            "connection_params": { 
              "url": "wss://speech-qa.verbit.co/ws?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJjdXN0b21lcl9pZCI6MTcwNiwiY3VzdG9tZXJfbmFtZSI6Ik9yZGVyaW5nX3Rlc3QiLCJvcmRlcl9pZCI6IjdkMWY4ODQxLWJjZjUtNGNhNy05MzNlLTI2Y2M4MzNiMWE0ZiIsInZhbGlkX2Zyb21fdHMiOjE2NzY2MjAxMjcuNjM5NzE1LCJ2YWxpZF91bnRpbF90cyI6MTY3NjY2NTQ4Ny42Mzk3MTUsIm9yZGVyX2l0ZW1faWQiOiI4MDEzZWJmOC1hMWRmLTQzM2MtYTQwMS01ZDUxN2RmMjM0NWIifQ.ukQ38osV1yHeg6L1Tlby9vUihg7KsWsnjJVk0cHoBK8XCiADNG42gHXDzYVeassexa1Hw9ccUkgbYWgYYU5BBsdVI3lpxdYQnBM5tvoHyJOho24XujorYRKKvFaQabg5j18eVSJbzVfaLi930nXQnfgHUJlX9xJ1N3_GcjBaMDaJZJfN6k_VUHDLecuR5Vf6TmsVTBxF8Upgi2ti_OR0YuSFCtDL6GN47OqF5wvV6yXRZwHz--8WODOxRnYbOqkHfKhASVRPpott2yvsqUt20vpfMhMvGDVD2Gy4sdV5DgXY0aDoXvIs3ao1ME8zpBAtQqkvg" 
            } 
          } 
        ], 
        "status": { 
          "name": "created", 
          "message": "Order '7d1f8841-bcf5-4ca7-933e-26cc833b1a4f' is created" 
        } 
      } 
    ], 
    "service_type": "live", 
  } 
} 

Contact Email

For API related inquiries, you may contact Verbit by sending a direct e-mail to api@verbit.ai.

Related articles

Powered by Zendesk