Recorded Media API Integration

• 1. Purpose of this document
• 2. Support and contact
• 3. Billing
• 4. Integration overview
  • 4.1. Ai-Media's Orders API
  • 4.2. Integration patterns
• 5. Concepts and terminologies
• 6. Orders API Overview
• 7. Orders API Endpoints
  • 7.1. Regions
  • 7.2. Status page
  • 7.3. Authorisation
  • 7.4. Billing
  • 7.5. Staging and testing
  • 7.6. Rate limits
  • 7.7. Conventions
  • 7.8. OpenAPI document
  • 7.9. GET /orders/{id}
  • 7.10. POST /orders
  • 7.11. POST /orders/validate
  • 7.12. GET /orders
  • 7.13. GET /voices
  • 7.14. GET /topic-models
  • 7.15. GET /languages
  • 7.16. GET /translation-languages
  • 7.17. GET|POST /order-items/{orderItemId}/output/{fileId}/convert
  • 7.18. GET /order-items/{id}
  • 7.19. POST /order-items/{id}/iterations
• 8. Build Integration with Orders API
  • 8.1. Get started
  • 8.2. Select order type
  • 8.3. Include more information in the order
  • 8.4. Store and retrieve custom data associated with orders
  • 8.5. Improve ASR accuracy with custom vocabulary entries
  • 8.6. Get desired spelling with substitutions
  • 8.7. Reuse custom vocabulary and substitutions with Topic Models
  • 8.8. Generate additional output formats
  • 8.9. Translate the spoken language
  • 8.10. Fine-tune the output
  • 8.11. Check order status
  • 8.12. Download output files
  • 8.13. Order details response - language-related fields
  • 8.14. Utilise the callback mechanism
  • 8.15. Field reference
• 9. Features
  • 9.1. Topic models
  • 9.2. Audio events
  • 9.3. LEXI AD
• 10. Supported Languages and Formats
  • 10.1. LEXI Recorded input and output languages
  • 10.2. LEXI Recorded additional translation languages
  • 10.3. LEXI Recorded Output formats
  • 10.4. LEXI AD output voices
  • 10.5. LEXI Voice for Recorded output voices

1. Purpose of this document

This document is designed to guide developers from Ai-Media's customer organizations in building API-based integrations for Recorded Media workflows. These workflows can leverage both AI-driven LEXI Recorded services and captioner-assisted Recorded Premium order types.

2. Support and contact

Latest version of this document can be found at https://doc.recorded.ai.media/api-integration/AIM_RM_API.html (PDF: https://doc.recorded.ai.media/api-integration/AIM_RM_API.pdf).

If you have questions or encounter issues, please reach out based on the type of support you need:

General Inquiries and Usage Support:

For questions about our services or assistance with order management, please contact:

• Your dedicated Account Manager
• The local Operations Team in your region
• The local Support Team in your region

If you are unsure who to contact, check Recorded Media Product Support page.

Technical and Integration Support:

For specific technical questions related to API usage or integration development, you will have direct communication with the product team based in Australia. Your Account Manager, Operations Team, or Support Team can assist in establishing this connection, ensuring you receive the appropriate assistance.

We are committed to providing timely and effective support to help you maximize the value of our services and integrate our API seamlessly into your systems.

3. Billing

There is no charge associated with the number of API requests made. Customers are billed based on the duration of the source media in their orders, and rates may vary depending on the type of order.

For any questions regarding billing, rates, invoices, or a cost waiver for testing, please contact your account manager or the operations team in your region.

4. Integration overview

4.1. Ai-Media's Orders API

Ai-Media offers robust integration capabilities and flexible architecture to seamlessly incorporate LEXI Recorded and Recorded Premium into end-to-end media production workflows. At the core of this integration is Ai-Media's Orders API, providing customers with the ability to initiate new orders, monitor order outcomes, receive real-time notifications for order status changes, and retrieve captions. The developer-friendly nature of the API is attributed to its adherence to industrial standards, including REST, JSON, API key, HTTPS, and TLS, making it straightforward to navigate and easy to work with. This single API interface supports both AI-fulfilled LEXI Recorded and captioner-fulfilled Recorded Premium order types, facilitating a smooth transition between AI and captioner-based captioning without hassle or disruption.

4.2. Integration patterns

Recognizing the diversity of production workflows and unique business requirements, Ai-Media ensures that integration with its platform is not a one-size-fits-all approach. In response to this, Ai-Media summarized several architecture patterns that can be applied during the integration design process. These architecture patterns serve as adaptable frameworks, allowing organizations to tailor the integration to align seamlessly with their distinct workflows and business specifications.

4.2.1. API based integration

Organizations endowed with software development capabilities, whether through in-house teams or external contractors and vendors, could build direct integration using Ai-Media's Orders API. This approach is future proof and grants maximum flexibility, enabling a customized integration aligned with the unique needs of the organization. By leveraging the Orders API, these organizations can seamlessly integrate Ai-Media's services with their internal systems and workflows. This method offers the highest degree of automation, minimizing daily operational efforts, and affords full control over intricate details such as the formatting of captions, selection of output languages, and the utilization of topic models. This level of control empowers organizations to tailor the integration to their precise specifications, fostering a seamless and efficient workflow that aligns with their specific business requirements.

This diagram below illustrates a solution based on API integration:

4.2.2. Shared folder based integration

For organizations seeking minimal involvement in software development, opting for a solution based on mutually accessible file storage, such as an AWS S3 bucket or SharePoint, can be a practical starting point. In this scenario, Ai-Media can periodically scan the designated input folder to identify and process new files. Once the caption file is ready, it is returned to the same folder or directed to a dedicated output folder, allowing to be retrieved. While this approach may not deeply integrate with the organization's internal workflows, making it less impactful in streamlining the end-to-end process, it presents a straightforward and easy-to-adopt solution for many organizations. This method minimizes implementation challenges and proves to be the least disruptive option, catering to organizations seeking a quick implementation with minimal software development involvement.

The shared folder could be provided by either the customer or Ai-Media. This diagram below illustrates the scenario that the customer provides the shared folder for Ai-Media to access:

4.2.3. Custom integration

For organizations that have already established standard interfaces for captioning service providers, Ai-Media offers to develop integrations based on their existing interface specifications. This tailored approach allows Ai-Media to support those organizations to offer advanced captioning services to their customers.

This diagram below illustrates how Ai-Media can join the ecosystem and offer its services through the platform:

5. Concepts and terminologies

6. Orders API Overview

The diagram below illustrates how fully automated integration via the Orders API can complement or replace the manual workflow managed through the web portal. With the Orders API, manual intervention becomes optional, allowing for a more streamlined and automated process.

By utilizing the Orders API, customers can automate the entire workflow from order creation to completion, significantly reducing manual efforts and improving efficiency. The flexibility of this API allows for seamless integration into existing systems, supporting various media processing needs with minimal manual intervention.

Here's a breakdown of how this workflow operates:

6.0.1. Create Order (REST API)

The integration begins with the customer's system sending a POST request to the Orders API to create a new order. This request includes all necessary details, such as the type of service required, the source media URL, and language settings. The API responds with a unique customerOrderId, which will be used for tracking and managing the order.

6.0.2. Get Order Details (REST API)

After the order is created, the customer can retrieve detailed information about the order by sending a GET request to the Orders API, using the customerOrderId. This endpoint provides the current status of the order, including whether it's in progress, completed, or if any issues have arisen. If the order is in a completed state, the response will also include the outputs associated with the order, such as caption files generated during processing.

6.0.3. Order Status Change Callback (Optional)

To further streamline the process, the customer can set up a callback endpoint. This is an optional feature where Ai-Media will automatically send a notification to the customer's system whenever there is a status change in the order. This eliminates the need for continuous polling and allows the customer's system to react immediately to status updates.

If the callback endpoint is configured, it will receive notifications about any changes in the order's status, such as completion or failure. This allows the customer's system to handle these updates automatically, such as by downloading the final output or triggering additional workflows based on the order's completion.

6.0.4. Query Orders (REST API)

The Orders API also provides an endpoint for retrieving list of orders within specified time window. The response provides a summary for each matching order.

Please note that only orders created within 400 days are available for query.

7. Orders API Endpoints

7.1. Regions

Orders API is available in the following regions:

• Australia (https://au.api.orders.ai.media/orders)
• Europe (https://eu.api.orders.ai.media/orders)
• The United States (https://us.api.orders.ai.media/orders)

It is recommended to use the API endpoint in the closest region to the caller of the API.

7.2. Status page

Availability of the API and incidents are published through the status page under "Recorded Cloud" group. The status page is accessible through the link https://aimedia.statuspage.io/.

7.3. Authorisation

To successfully invoke the API, a valid API key must be included in the "x-api-key" header of the request.

7.4. Billing

Ai-Media does not charge for API calls. Customers are billed based on the duration of the source media in their orders; rates may vary by order type.

If you would like to request a waiver of service usage costs during your development or testing phase, please contact your dedicated account manager or email recorded.services@ai-media.tv.

7.5. Staging and testing

There is no separate self-serve sandbox product or staging/testing environment. For integration development and testing, use API key provided by AI-Media for production environment.

Orders created in during development and testing still consume processing capacity and would incur usage charges unless a cost waiver has been arranged.

7.6. Rate limits

The Orders API does not currently have request-rate or concurrency quotas or limitations. AI-Media does not charge per API call; however, clients should still make requests at a reasonable rate (for example, avoid tight polling loops when a callbackUrl can be used instead).

If you expect sustained high-volume traffic (bulk order creation, aggressive polling, or large parallel conversion workloads), contact AI-Media before go-live so capacity can be reviewed.

7.7. Conventions

All requests sent to and responses received from the Orders API use the "application/json" content type.

In cases where an error occurs, the Orders API will return a response with an HTTP status code indicating the nature of the error (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found). The response body will follow a standard structure in JSON format:

{
  "message": "details of the error"
}

Sometimes the response also include a correlationId field. Please include that value when contacting support.

7.7.1. Error reference

The message string is the primary signal for diagnosing failures. Common statuses and representative messages are listed below. Exact wording may vary slightly (for example when a URL, language code, or field path is interpolated).

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Use POST /orders/validate during integration development to surface validation messages without submitting a billable order.

7.8. OpenAPI document

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service. The OpenAPI document for the Orders API is available at https://doc.recorded.ai.media/api-integration/swagger-ui/index.html .

7.9. GET /orders/{id}

This endpoint can be used for getting order details, checking order status and getting order outputs.

Customer order ID can be specified as part of the URL path. If there's no order found by that ID, a 404 response will be returned. Otherwise, the full details of the order will be returned.

The response includes the externalIntegrationId and externalIntegrationData fields if they were provided when creating the order. These fields can be used to retrieve custom data you stored with the order.

Each order item in the response includes an actionsRequired array, listing the steps that are waiting on a human before the order item can go any further, such as labelling people or editing the AD script. It is empty when nothing is pending. Every entry has a label describing the action, a url at which to perform it, and a role array saying who the action is for: user for actions the customer performs and coordinator for actions Ai-Media performs. To show a customer only what they can act on, keep the entries whose role contains user. Pending actions are reported here and nowhere else — the output array holds downloadable files only.

Each order item in the response includes a canStartNewIteration field for Iterative LEXI AD order types (see LEXI AD order types); it is omitted for all other order types. It is true when a new iteration can be started, taking into account both the 7-day time window since order creation and how far the order item has got — it is false while audio description is still being produced, because a new iteration started then would discard the work in progress. The requirements it reflects are the same ones POST /order-items/{id}/iterations enforces, so the two cannot disagree. It remains a point-in-time answer: an order item can move on between the field being read and an iteration being requested, so the request itself may still be refused.

7.10. POST /orders

This endpoint can be used for submitting a new order.

Details of the new order should be included in the request body.

If the order is successfully submitted, its customer order ID and order reference will be included in the response body. If the order details do not pass validation, detailed error message will be returned in a 400 response.

The duration of the source media is inspected during validation and must not exceed the maximum allowed for the order type:

When the source media is longer than the allowed maximum, a 400 response is returned with a message of the form Source media at location '<url>' has duration <seconds>s which exceeds the maximum of <seconds>s allowed for order type '<orderType>'.

7.11. POST /orders/validate

This endpoint can be used for validating new order details without actually submitting it.

Details of the new order should be included in the request body.

If the order is successfully validated, a 204 response will be returned. Otherwise, detailed error message will be returned in a 400 response. The same source-media duration limits documented for POST /orders apply here.

7.12. GET /orders

This endpoint can be used for querying orders with pagination. Filtering condition can be specified in query string.

• start - The earliest creation time of the orders to be retrieved, in ISO 8601 format UTC, e.g. 2024-01-01T00:00:00.000Z, inclusive. It can be omitted if a lower boundary of creation time is not desired.
• end - The latest creation time of the orders to be retrieved, exclusive, with specific behaviour depending on the page being queried. First Page: When retrieving the first page, this value specifies the latest creation time (exclusive) of the orders to be retrieved, formatted as an ISO 8601 timestamp UTC (e.g., 2025-01-01T00:00:00.000Z). It can be omitted if a upper boundary of creation time is not desired. Subsequent Pages: When retrieving subsequent pages, this value must be set to the uniqueOrderCreatedTimestamp value of the last (earliest) order from the page returned from previous API call. The value of uniqueOrderCreatedTimestamp field looks like 2024-10-01T04:21:30.831Z_65d2f5b9-aaef-4d8a-8e4a-5ffeadf4093f.
• allRegions - Whether the query should be performed on orders in all regions. If omitted or set to false, the query is performed on orders in the same region as the API endpoint.

Response body from this endpoint is an array of order summaries. Orders in the array are sorted by creation time in descending order.

Each order summary in the response includes the externalIntegrationId and externalIntegrationData fields if they were provided when creating the order. These fields can be used to retrieve custom data you stored with the order.

To retrieve all the orders through pagination, the logic below can be followed:

1. Get these variables ready: start (optional), end (optional). They specify the desired time window for the query.
2. Get ready an empty array for keeping all returned order summaries, let's name it results.
3. While number of elements in results is less than the number you need, repeat the following:
   1. Retrieve a page with start and end as parameters.
   2. If the page is empty, break out from the "while" loop.
   3. Append the order summaries just retrieved to results.
   4. Get the value of the uniqueOrderCreatedTimestamp field on the last order just retrieved, and set it as the new value of end
4. Now results should contains all the order summaries you need.

7.13. GET /voices

This endpoint allows you to retrieve available voices for a specific language code. This is useful when configuring text-to-speech or voice synthesis options for your orders, particularly for narration services like LexiAD.

Query Parameters:

• language (required): The language code to get available voices for (e.g., en-US, en-GB, en-AU)
• orderType (optional): Order type to filter voices by order type.

Response: The endpoint returns an array of voice objects, each containing a code, descriptive name, and optional sample URL for audio preview:

[
  {
    "code": "en-au-william",
    "name": "William (Male, Australian)",
    "sampleUrl": "https://d136xw242vw8vv.cloudfront.net/voice-samples/en-AU_en-au-william.mp3?Expires=..."
  },
  {
    "code": "en-au-neil",
    "name": "Neil (Male, Australian)"
  }
]

7.14. GET /topic-models

This endpoint allows you to retrieve available topic models for your customer account. Topic models are predefined sets of custom vocabulary and substitution rules that can be reused across multiple orders.

Query Parameters:

• customerName (optional): The customer name to get available topic models for. This parameter is only effective if the caller is an internal staff member or coordinator. If omitted, the topic models available to the authenticated customer will be returned.

Response: The endpoint returns an array of topic model identifiers (strings). Shared common topic models (managed by Ai-Media) are listed first and have the ai-media/ prefix, followed by customer-specific topic models in alphabetical order.

[
  "ai-media/disfluency",
  "ai-media/profanity",
  "my-custom-model",
  "sports-terminology"
]

• Topic models with the ai-media/ prefix are shared common topic models managed by Ai-Media that are available to all customers.
• Topic models without the prefix are customer-specific models.

7.15. GET /languages

This endpoint allows you to retrieve all available languages with their codes and names. You can optionally filter by order type and input language to get only the languages that are supported for specific scenarios.

Query Parameters:

• orderType (optional): The order type to get available languages for (e.g., ASR, LexiAD, Translation)
• inputLanguage (optional): The input language to get available languages for

Response:

[
  {
    "code": "en",
    "name": "English"
  },
  {
    "code": "es",
    "name": "Spanish"
  },
  {
    "code": "fr",
    "name": "French"
  }
]

7.16. GET /translation-languages

This endpoint allows you to retrieve all available translation languages with their codes and names. You can optionally specify a source language to get only the languages that are supported for translation from that source.

Query Parameters:

• sourceLanguage (optional): The source language to get available translation languages for. If omitted, returns all supported translation languages.

Response:

[
  {
    "code": "es",
    "name": "Spanish"
  },
  {
    "code": "fr",
    "name": "French"
  },
  {
    "code": "de",
    "name": "German"
  }
]

7.17. GET|POST /order-items/{orderItemId}/output/{fileId}/convert

This endpoint allows you to convert order item output files from one format to another. Currently supports converting SRT and VTT format outputs to other formats such as DOCX, STL, TTML, DFXP, MCC, and SCC.

Both GET and POST methods are supported. Use POST when you need to specify additional conversion options in the request body.

Path Parameters:

• orderItemId (required): The ID of the order item containing the output to convert
• fileId (required): The file ID of the output document to convert

Query Parameters:

• outputFormat (required): The desired output format code (e.g., docx, stl, ttml, dfxp, mcc, scc-29.97fps-df)

Request Body (POST only, optional): When using POST, you can include additional conversion options in the request body as JSON:

{
  "includeFormatting": true
}

• includeFormatting (optional, boolean): Whether to include formatting in the converted output. If not specified, defaults to the service's default behavior.

Requirements:

• The input file must be in SRT or VTT format
• The output format must be a valid conversion target format (see supported output formats table)

Response: The endpoint returns the converted file as binary content with appropriate headers:

• Content-Type: application/octet-stream
• Content-Disposition: attachment; filename="<original-filename>.<extension>"

Error Responses:

• 400: Bad request (e.g., invalid output format, invalid input format)
• 404: Order item or output document not found
• 403: Insufficient permissions
• 500: Internal server error

Examples:

GET /order-items/item123/output/file456/convert?outputFormat=docx

POST /order-items/item123/output/file456/convert?outputFormat=docx
Content-Type: application/json

{
  "includeFormatting": true
}

7.18. GET /order-items/{id}

This endpoint returns details for a single order item together with its parent order (without sibling items).

Order item ID can be specified as part of the URL path. If there's no order item found by that ID, a 404 response will be returned. Otherwise, the response body matches GetOrderItemDetailsOutput from @ai-media/common-common:

• orderItem — the requested item in the same shape as an element of GET /orders/{id} orderItems
• order — parent order fields from GET /orders/{id}, excluding orderItems

Authorisation is evaluated against the requested item only (not sibling items on the parent order).

7.19. POST /order-items/{id}/iterations

This endpoint starts a new iteration (in-place rework) on an existing Iterative LEXI AD order item. It applies optional setting changes from the request body, selectively re-enters the LEXI AD workflow, and returns any next pending actions for the caller.

Request and response bodies follow the CreateIterationInput and CreateIterationOutput types from @ai-media/common-common.

Path Parameters:

• id (required): Order item ID. Supplied to the service as CreateIterationInput.orderItemId (do not send orderItemId in the request body).

Request Body: Corresponds to CreateIterationInput from @ai-media/common-common, excluding orderItemId (taken from the path).

CreateIterationInput is a partial of CreateOrderInputItem plus a partial pick of order-level CreateOrderInput fields, with one iteration-specific property:

IterationStartAt values (LEXI AD):

Nested shapes for overrides match order creation (AudioDescriptionOptions, OrderOutputOptions, etc.). See Field reference and LEXI AD. Iteration is order-type specific; not all override fields are supported for all order types.

Changing audioDescription.startTime or audioDescription.endTime requires the iteration to start at AD script generation or earlier (GenerateAdScript or LabelFaces). Starting at ReviewAdScript or GenerateOutputs while changing those fields is rejected with HTTP 400, because those steps reuse the existing AD script.

Example request body (CreateIterationInput without orderItemId):

{
  "startAt": "GenerateAdScript",
  "customerInstructions": "Prefer concise descriptions of on-screen text.",
  "audioDescription": {
    "adScriptNeedsEditing": true,
    "noSpeechInSourceMedia": false,
    "maxCharactersRatio": 1,
    "minimumGapBetweenConversations": 3000,
    "maxPreConversationOverlap": 0,
    "maxPostConversationOverlap": 0,
    "startTime": 5000,
    "endTime": -2000
  },
  "outputOptions": {
    "audioDescription": {
      "generateAdAudio": true,
      "generateAdAudioInWav": true,
      "generateAdAudioInMp3": false,
      "generateAdVideo": true,
      "generateAdMixedInOriginal": false,
      "generateAdScript": true,
      "generateTranscript": false,
      "generateSourceMediaMetadata": false,
      "generateSourceMediaDescription": false
    }
  },
  "outputLanguages": [
    {
      "code": "en-AU",
      "voice": {
        "name": "en-au-william",
        "rate": 1
      }
    }
  ]
}

Requirements:

• The order item must be an Iterative LEXI AD order type
• The audio description pipeline must not be working on the order item. It is either finished (Completed, Failed or Cancelled) or stopped waiting for someone to label people or edit the AD script. Requests made while transcription, people identification, AD script generation or mixing in is under way are rejected, because a new iteration would discard that work.
  • This applies to an order item that has already been delivered and is being reworked as well: its status stays Completed for the whole of the iteration, so a further iteration is refused until that one finishes.
• The order must have been created no more than 7 days ago. Once that window has passed, this endpoint returns a 400 response whatever state the order item is in.
• Changing audioDescription.startTime or audioDescription.endTime is only allowed when the iteration starts at GenerateAdScript or LabelFaces. Requests that change those fields while starting at ReviewAdScript or GenerateOutputs are rejected with HTTP 400.

Callers can check the canStartNewIteration field on the order item (see GET /orders/{id}) to know in advance whether a new iteration can be started; it is derived from these same requirements.

Response (200): Corresponds to CreateIterationOutput from @ai-media/common-common:

Each pendingActions element is an OutputFile:

Example:

{
  "id": "iteration-id",
  "orderItemId": "order-item-id",
  "customerOrderId": "customer-order-id",
  "pendingActions": [
    {
      "role": "PendingAction",
      "name": "Edit AD script",
      "url": "https://…",
      "format": "actionUrl",
      "fileId": "…"
    }
  ]
}

If pending actions are not ready when the handler returns, call GET /orders/{id} to refresh.

Error Responses:

• 400: Bad request (e.g. not an Iterative LEXI AD item, status gate failed, invalid JSON)
• 404: Order item not found, or the caller is not allowed to access it
• 403: Insufficient permissions for the operation

8. Build Integration with Orders API

8.1. Get started

With your API key in hand and your chosen endpoint region determined, you can start with initiating an order validation request.

Below is an example of an order validation/creation request payload:

{
  "orderItems": [
    {
      "orderType": "BasicLexi",
      "sourceMediaUrl": "https://your-domain/your-file.mp4",​
      "inputLanguage": "en",​
      "outputLanguage": "en-AU",
    }
  ]
}

To validate the order details, send a POST request with the above payload to https://au.api.orders.ai.media/orders/validate (or the equivalent endpoint in another region). A 204 No Content response indicates that the payload is valid.

Once validated, you can then actually create the order by sending the same request body to https://au.api.orders.ai.media/orders (or the equivalent endpoint in another region). A successful creation will return a 200 OK response with a body like this:

{​
  "customerOrderId": "c32e2e37-1ea7-4e3a-9be8-1955d6948067",​
  "orderReference": "b0ij6ikckv"​
}​

• customerOrderId: The unique identifier for the order.​
• orderReference: A reference ID, typically used for UI purposes.​

After the order is created, you can monitor its status by sending a GET request to https://au.api.orders.ai.media/orders/{customerOrderId} (or the equivalent endpoint in another region).

The response will include a status field that indicates the current status of the order. If the order is completed, each item in the orderItems array will contain an output array with download links of output files.

8.2. Select order type

The orderType field on order item allows the type of the order to be specified.

For "LEXI Recorded", the fully automatic AI fulfilled captioning/transcribing service, the orderType is BasicLexi.

For "LEXI AD", order types combine Standard vs Extended AD with independent face-labelling and AD script-editing options:

Only BasicLexiAD and BasicExtendedLexiAD are automatically fulfilled. Types that require customer or AI-Media face labelling and/or AD script editing are not automatically fulfilled (API keys need the corresponding non-auto-fulfilled permissions).

For every Extended LEXI AD order item, audioDescription.extendedAdLengthTargetRatio is required (allowed range 1.1–2). Types with customer AD script editing use audioDescription.adScriptNeedsEditing to opt into the pause; types with AI-Media AD script editing always pause for that step. See LEXI AD specific order creation request fields.

Captioning is the most common order type for captioning done by professional captioners.

For order types of other services, please contact your local Ai-Media operations team or customer success team, or your account manager.

The order type must be configured for the customer account before an order of that type can be created. If the order type is not configured or does not have correct rate configuration, order creation or validation would fail with this kind of message: Rate is not configured for CustomerName: [<customer name>], OrderType: [<order type>], ....

8.3. Include more information in the order

To include additional details in the order, use the optional customerInstructions field, which accepts a string.

Please note that any text provided in the customerInstructions field will not be utilized for AI-fulfilled orders. However, for orders fulfilled by professionals, coordinators and captioners may find this information helpful.

8.4. Store and retrieve custom data associated with orders

To store custom data associated with orders that can be retrieved later when fetching order details or querying orders, use the following fields:

At the order level:

• externalIntegrationId - A string field for storing an identifier (e.g., your internal order ID, ticket number, or reference)
• externalIntegrationData - An object field for storing additional custom data (e.g., metadata)

These fields are optional when creating orders and will be included in the response when getting order details via GET /orders/{id} or when querying orders via GET /orders.

At the order item level: If you need to store custom data at the order item level instead, you can use the following fields which are also returned in order details responses:

• customerReference - Customer's reference for the order item
• episodeNumber - Episode number
• episodeTitle - Title of the episode
• seriesNumber - Series number
• seriesName - Name of the series

8.5. Improve ASR accuracy with custom vocabulary entries

The customVocabularyEntries field allows you to provide an array of custom vocabulary entries that can enhance the accuracy of Automatic Speech Recognition (ASR).

Value in this field should be structured as follows:

"customVocabularyEntries": [
  {
    "content": "Haksabanovic",
    "soundsLike": ["hack-shuh-ban-oh-vich", "hack-su-ba-no-vich"]
  }
]

• content: The word or phrase that needs to be recognised.
• soundsLike: An array of phonetic representations to guide the ASR in accurately recognizing the content.

This field is optional, but including custom vocabulary entries can significantly improve the accuracy of the ASR, especially for names, technical terms, or uncommon words.

8.6. Get desired spelling with substitutions

The substitutions field is an optional array of entries that can be used to refine the text in output.

Value in this field should be structured as follows:

"substitutions": [
  {
    "fromText": "colour",
    "to": "color",
    "partialMatch": false
  }
]

• fromText: The plain text to be replaced. It is case sensitive.
• to: The text that will replace the fromText.
• partialMatch: A boolean value indicating whether the substitution should only apply to whole words or phrases. The default value is false. When partialMatch is false, the fromText should be surrounded by specific characters (like spaces or line breaks) or positioned at the start or end of a line.

Use Cases:

• Spelling Corrections: For example, making sure the spelling of a build's name is correct.
• Profanity Filtering: Replace inappropriate language.
• Disfluency Filtering: Remove or replace verbal fillers or repeated words.
• Spelling Variants: Apply preferred spelling conventions (e.g., "centre" to "center").

Substitution is applied before translations specified in translationLanguages. When human captioners fulfil the order, substitutions are applied to their output.

8.7. Reuse custom vocabulary and substitutions with Topic Models

To reuse custom vocabulary entries and substitutions across multiple orders, you can utilize a "topic model." A topic model is a predefined set of vocabulary entries and/or substitutions that can be applied consistently across different orders.

The topicModelIds field is an optional array that allows you to specify the identifiers of these topic models. When multiple topic models are specified, their vocabulary entries and substitution entries are merged in a "right-overrides-left" manner. This means that if there are conflicting entries, the entries from the topic model listed later in the array will override those from the earlier ones.

After merging the entries from the specified topic models, the entries provided directly in the customVocabularyEntries and substitutions fields will further override and merge with those from the topic models. This final set of entries is then applied to the order.

Using topic models simplifies the management of common vocabulary and substitution rules, ensuring consistency and reducing the need for repeated entries in each order.

There are two ways to have topic models defined:

• EEG Cloud:

  • EEG Cloud offers a web-based UI for managing topic models.
  • To obtain the topic model identifier for a topic model defined in EEG Cloud, contact your EEG Cloud support team.

• Shared Excel File:

  • Topic models can also be set up in a shared Excel file provided by Ai-Media.
  • For setting up a topic model using this method, contact your local Ai-Media operations team.

Depending on the business terms agreed upon, the maintenance and management of topic models can also be delegated to Ai-Media's local operations team.

A "default" topic model can be set up per customer as a shared Excel file. This "default" topic model will automatically apply to all orders created for the customer.

8.8. Generate additional output formats

The additionalOutputFormats field is an optional list that allows you to request output files in formats beyond the standard srt and docx, which are automatically generated by the system.

By specifying this field, you can receive additional files in other formats, tailored to your specific needs. For example:

"additionalOutputFormats": [ "scc-29.97fps-df", "ttml" ]

8.9. Translate the spoken language

By specifying a language different than the spoken language in the input as the output language, you can tell the system to do translation. Content of the output files will be in the specified output language.

You can also specify multiple translation languages in the optional translationLanguages field. Additional translation uses the output language as the source, so that when specifying translation languages, you may want to make sure the output language is the same as the input language, to avoid double translation.

For each of the specified translation language, the system generates a set of output files in that language.

8.10. Fine-tune the output

To customize the format of your output files, you can use the optional outputFormatting and outputOptions fields. These fields allow you to fine-tune various aspects of the generated files to meet specific requirements.

8.10.1. Output formatting

The outputFormatting field provides several options for controlling the appearance and structure of your output files:

"outputFormatting": {
  "lineEnding": "\n",
  "speakerChangeIndicator": "-- ",
  "subtitleSection": {
    "maxLineLength": 42,
    "maxLines": 2,
    "minimumDuration": 1
  }
}

• lineEnding: Specifies the type of line ending to be used in the output file. Options include \n, \r, \r\n, and \n\r.
• speakerChangeIndicator: Allows you to define how speaker changes are indicated in the output. This can be a string literal or a format like "S#: " for indicators such as "S1: " or "S2: ".
• audioEventWrapper: Wrapper characters that enclose audio event labels (e.g. [applause] or (applause)). Object with open and close string properties. Default when not specified is square brackets ({"open":"[","close":"]"}).
• subtitleSection: Contains settings for subtitle formatting:
  • maxLineLength: Sets the maximum number of Latin characters allowed per subtitle line, including spaces. Please note that for some of the non-western languages, the character is twice the width of a Latin character.
  • maxLines: Defines the maximum number of lines allowed in a subtitle section.
  • minimumDuration : Defines the minimum duration of a subtitle block in seconds.
  • backgroundColour: Background colour of the subtitles. Supported values: black, white, red, lime, yellow, blue, magenta, cyan. If omitted, background is usually transparent/no-colour.

Formatting is applied to both native and translated captions. When human captioners fulfil the order, formatting is applied to their output.

8.10.2. Output options

The outputOptions field provides further customization. There is captions.startTime setting and it applies only to SCC outputs. Another setting is audioDescription which applies only to LEXI AD orders.

"outputOptions": {
  "captions": {
    "startTime": "00:30:05;00"
  },
  "audioDescription": {
    "generateAdMixedInOriginal": true,
    "generateTranscript": false,
    "generateAdScript": true,
    "generateAdAudio": true,
    "generateAdAudioInMp3": false,
    "generateAdAudioInWav": true,
    "generateAdVideo": true,
    "generateSourceMediaMetadata": true,
    "generateSourceMediaDescription": true
  }
}

• startTime (under outputOptions.captions):
  • This setting allows you to offset the timecodes in the captions.
  • It can be specified as a SMPTE timecode (e.g., "00:30:05;00" or "00:30:05:00") or as a number of milliseconds.
• LEXI AD flags (under outputOptions.audioDescription):
  • These options apply only to LEXI AD order types. If omitted, documented defaults apply on the server (see field table below).
  • generateAdMixedInOriginal: If true, generates original-quality video with AD mixed in. Default if omitted: false.
  • generateTranscript: Whether to generate the transcript of the source media. Default if omitted: false.
  • generateAdScript: Whether to generate the audio description script. Default if omitted: true.
  • generateAdAudio: Whether to generate audio description audio assets (e.g. ducked/mixed tracks). Default if omitted: true.
  • generateAdAudioInWav: Whether to generate AD audio in WAV format. Default if omitted: true.
  • generateAdAudioInMp3: Whether to generate AD audio in MP3 format. Default if omitted: false.
  • generateAdVideo: Whether to generate AD-related video outputs (proxy and, when enabled, full-quality). Default if omitted: true.
  • generateSourceMediaMetadata: Whether to generate the source media metadata file. Default if omitted: true.
  • generateSourceMediaDescription: Whether to generate the source media description file. Default if omitted: true.

8.11. Check order status

In the order details returned from the API, there is a status field for the whole order, and also a status field for each of the order items.

Below are the possible values of the status field:

• Received: It has been received, but the system has not started processing it.
• Created: It has been received and the system has just started processing it.
• InProgress: It is being processed.
• Completed: The processing has completed, output files are ready.
• Failed: Processing failed.
• Cancelled: It has been manually cancelled by a coordinator.

Output files are ready for download when the status is "Completed".

8.12. Download output files

When the status is "Completed" in the order details returned from the API, each order item has an output field with value like this:

"output": [
  {
      "role": "Captions",
      "format": "srt",
      "name": "demo-sample_zh.srt",
      "language": "zh",
      "url": "https://example.com/download/file.srt?access-token=secret",
      "fileId": "b76c1bc1-ad47-45b2-bf4f-780cdc02c280"
  }
]

• The role property indicates what the output file is about.
• The format property indicates the format of the output file. For the list of possible values, see the "Supported Languages and Formats" section of this document.
• The entries without language field are for the output language.
• The entries with language field are for the corresponding translation language. For the list of possible values, see the "Supported Languages and Formats" section of this document.
• The URL can be used to download the output file. It has a 7 day expiration counting from the time the order detail is returned.

This array holds downloadable files only. Steps waiting on a human, such as labelling people or editing the AD script, are reported in actionsRequired instead (see GET /orders/{id}).

8.13. Order details response - language-related fields

When retrieving order details via GET /orders/{id} or when querying orders via GET /orders, the response includes language and voice related fields that mirror or derive from the order creation request:

8.14. Utilise the callback mechanism

To enhance the efficiency of your order processing, you can utilize the optional callback feature provided by Ai-Media. This feature allows your system to receive real-time notifications whenever there is a status change in your order, eliminating the need for continuous polling and enabling immediate reactions to status updates.

To utilise the callback mechanism, specify the URL where you want to receive notifications in the callbackUrl field, like this:

"callbackUrl": "https://your-api.example.com/webhook/orders"

Use an HTTPS URL that is reachable from the public internet. Ai-Media sends a POST request with Content-Type: application/json when an order's status changes. The payload is similar to:

{
  "id": "a34e2e37-2ea7-4e3a-1bb8-1955d6947067",
  "orderReference": "b7ij1ikcxv",
  "externalIntegrationId": "TICKET-12345",
  "status": "Completed"
}

If the callback endpoint is temporarily unavailable, Ai-Media will keep invoking it every 5 minutes for up to 2 hours.

8.14.1. Callback security

Callbacks are currently delivered without a shared-secret signature, HMAC, or other verification header. However, the callback URL can include anything that could be utilised for authentication or authorisation.

Recommended handling:

1. Accept the POST quickly and return 2xx.
2. Always call GET /orders/{id} with your API key to confirm the current status and retrieve outputs.
3. Prefer HTTPS callback URLs; do not expose sensitive data in the callback path or query string.
4. Optionally correlate using id / externalIntegrationId values that your system already knows from order creation.
5. Include a unique and hard-to-guess string in the URL for authentication or authorisation

Periodical polling and callback are usually used together. Below is a typical workflow:

1. Receive Callback: Your system receives a notification from Ai-Media with the status update.
2. Retrieve Order Details: Call the REST API to get complete details about the updated order.
3. Handle Updates: Process the retrieved order details to perform actions such as downloading the final output or triggering additional workflows.
4. Periodic Checks: Regularly check the status of all in-flight orders through the REST API to ensure you capture any updates that might have been missed.

8.15. Field reference

The tables below provide a quick reference for all available fields when creating orders through the API, organized by mandatory/optional status:

8.15.1. Order-level mandatory fields

These fields are required at the top level of the request:

8.15.2. Order-level optional fields

These fields are optional at the top level of the request:

8.15.3. OrderItem-Level Mandatory Fields

These fields are required within each element of the orderItems array:

8.15.4. OrderItem-Level Optional Fields

These fields are optional within each element of the orderItems array:

9. Features

9.1. Topic models

9.1.1. Topic models overview

A topic model is a predefined set of vocabulary entries and substitution rules that can be applied consistently across multiple orders. Using topic models helps maintain consistency in terminology, reduces the need for repeated entries, and ensures accurate processing of domain-specific terms.

Topic models contain:

• Substitutions: Allow users to replace words, phrases, or text in subtitles. (Only applied to BasicLexi orders.)
• Custom Vocabulary Entries: Allow users to define alternative pronunciations for words.

Topic models can be maintained in a centralized location and reused across multiple orders. Supported sources include:

• Specified as the name of the shared Excel file: Stored on SharePoint folders, created by Ai-Media but editable by the customer.
• Specified as EEG Cloud topic model ID: Provides a web-based UI for managing topic models.
• Specified directly in the order creation request: Defined at the time of order submission.

Substitution feature support across sources:

• Shared Excel file: Supports word-bonded or partial match, case-sensitive.
• EEG Cloud: Supports case-sensitive and case-insensitive matching (always word-bonded).
• Part of order creation request: Supports word-bonded or partial match, case-sensitive, and also supports regex-based rules.

9.1.2. Getting topic model IDs

Using Shared Excel Files

A topic model can be defined in an Excel file stored on SharePoint. If a file named default.xlsx is present, its content is automatically applied to all orders for that customer. If additional topic models are specified in the API request, their content overrides the default topic model, and inline topic model content in the order takes the highest precedence.

For assistance in setting up shared Excel-based topic models, customers should contact Ai-Media operations support.

Using EEG Cloud

For customers already using EEG Cloud, topic models can be referenced using a unique identifier. The identifier consists of an API key and a GUID, formatted as api_key_<API-KEY>:<TOPIC-MODEL-GUID>

To obtain a topic model identifier, customers can either contact EEG Cloud support or retrieve it through self-service methods. Since anyone with the identifier can apply it to any order, it must be handled securely.

When an order specifies both inline topic model content and EEG Cloud topic models, the two sources are merged, with the inline content taking precedence in case of conflicts.

9.1.3. Specifying topic model IDs in API requests

The topicModelIds field in the API request allows specifying one or multiple topic models to be applied to an order. When multiple topic models are provided, their entries are merged using a "right-overrides-left" approach, meaning later-listed models override conflicting entries from earlier ones.

9.2. Audio events

BasicLexi order type supports automatic detection of audio events in captions. Customers can enable this feature to include non-verbal audio cues, such as music, applause, and laughter, in their captions.

To enable audio event detection in an order, specify the desired event types in the API request using the audioEvents field:

"audioEvents": ["music", "laughter", "applause"]

Each type of audio event can be toggled on or off individually. If audioEvents is not specified, no audio events will be detected or included in the output.

If the order includes translation, detected audio events will be described in the target language(s).

9.3. LEXI AD

LEXI AD is a fully automated, AI-based service that generates audio descriptions for video content. It offers a fast and affordable solution for adding audio descriptions at scale, making it ideal for organizations looking to improve accessibility without the high costs and long turnaround times of human-created descriptions. With customizable input options — including video introductions and additional guidelines — LEXI AD provides flexibility while enabling seamless automation. Optional face detection can also help identify and label faces for more contextualized descriptions.

9.3.1. LEXI AD order types

LEXI AD order types combine standard vs extended AD with independent face-labelling and AD script-editing options:

• Face labelling URL (when applicable) is provided via the API and web portal; the order cannot complete until labelling is done.
• After an Iterative LEXI AD order item reaches a suitable state (Completed / Failed / Cancelled, or InProgress waiting on face labeling or AD script editing), a new iteration can be started via POST /order-items/{id}/iterations — but only within 7 days of the order's creation time; after that window, the endpoint rejects the request regardless of status.

9.3.2. LEXI AD specific order creation request fields

When creating a LEXI AD order, the following fields are particularly relevant:

• sourceTranscriptUrl: As part of the process, transcript of the source media is generated as input to downstream processing. If a transcript of the source media is already available, its access URL can be provided. This transcript will be used instead of generating a new one.
• videoIntroduction: A multiline text field that allows specifying an introduction to the video. This helps provide context for AI processing.
• customerInstructions: Additional instructions or guidelines for the audio description can be provided in plain English, allowing customization based on specific needs.
• audioDescription.maxCharactersRatio: Optional. Adjusts the maximum characters allowed for audio description in a given time window relative to the default (1 is recommended). If specified, the API enforces the range 0.6–1.1 (see implementation validation).
• audioDescription.extendedAdLengthTargetRatio: Required when any order item uses an Extended LEXI AD order type (any *ExtendedLexiAD type in the table above). Target ratio of extended AD duration vs standard AD (e.g. 1.5 targets 50% more AD time). Allowed range 1.1–2. Omit for non-extended LEXI AD orders.
• audioDescription.adScriptNeedsEditing: Customer AD script-editing types only (IterativeBasic*, IterativeCustomerAssisted*). When true, LEXI AD pauses after the AD script is generated and waits for the script to be edited manually before generating the audio description outputs; when false or omitted, outputs are generated as soon as the AD script is ready. For AI-Media AD script-editing types (ProfessionalAssistedIterative*, IterativeProfessionalAssisted*) the pause is part of the order type and always happens, so this field is ignored. This field can only be true when the order contains at least one Iterative LEXI AD order item; otherwise order creation fails with HTTP 400.
• audioDescription.startTime: Optional. Start of the segment to generate audio description for, in milliseconds from the beginning of the source media. Content before this time (for example a blank slate or clock) is skipped — no frame images, scene summaries, or audio description are generated for that period. Must not be negative. If omitted, processing starts at the beginning of the source media.
• audioDescription.endTime: Optional. End of the segment to generate audio description for, in milliseconds. A positive value is from the beginning of the source media and must be greater than startTime. A non-positive value is an offset from the end of the source media backwards (for example 0 means the end of the media, -2000 means 2 seconds before the end) — use this when the exact duration is not known when creating the order. If omitted, processing continues to the end of the source media. Values that fall outside the actual media duration are clamped during processing.
• outputOptions.audioDescription.*: Optional toggles controlling which LEXI AD outputs are generated; see Output options and the field reference table for defaults.

9.3.3. Specifying languages and voices for LEXI AD

Currently, LEXI AD automatically determines the input language. The inputLanguage field on the order item in the order creation request is ignored by LEXI AD and its value should always be set to en.

One or more output languages and their corresponding voices can be specified on the order item for LEXI AD.

When there is only one output language, the language, voice and rate can be specified like this:

{
  "orderItems": [
    {
      "inputLanguage": "en",
      "outputLanguage": "en-AU",
      "outputVoice": {
        "name": "en-au-william",
        "rate": 1
      },
      ...
    }
  ],
  ...
}

• outputLanguage is the code of the language that will be used for audio description.
• outputVoice.name is the code of the voice that will be used for generating the audio description audio.
• outputVoice.rate indicates how fast the audio description will be spoken. 1 is the normal speed, 1.1 is 10% faster, and 0.9 is 10% slower. rate is optional, and when omitted, the value 1 is applied.

When there are multiple output languages needed, they can be specified like this:

{
  "orderItems": [
    {
      "inputLanguage": "en",
      "outputLanguage": "en-AU",
      "outputVoice": {
        "name": "en-au-william"
      },
      "outputLanguages": [
        {
          "code": "zh-CN",
          "voice": {
            "name": "zh-cn-yunjian",
            "rate": 1
          }
        },
        {
          "code": "zh-TW",
          "voice": {
            "name": "zh-tw-hsiaochen"
          }
        }
      ],
      ...
    }
  ],
  ...
}

In the example above, audio description outputs in three languages will be generated: en-AU, zh-CN, and zh-TW.

If the same language appears in both outputLanguage and outputLanguages, those appearances will be merged automatically. rate is optional, and when omitted, the value 1 is applied.

A language can only be specified once on an order item regardless of whether there are different voice settings. For example, the following request is invalid:

{
  "orderItems": [
    {
      "outputLanguages": [
        {
          "code": "en-AU",
          "voice": {
            "name": "en-au-william",
          }
        },
        {
          "code": "en-AU", // invalid, even though it has a different voice
          "voice": {
            "name": "en-au-freya",
          }
        }
      ]
      ...
    }
  ],
  ...
}

9.3.4. LEXI AD outputs

By default (and subject to outputOptions.audioDescription.*), each completed LEXI AD order could have the following outputs:

• Audio description script - .srt file containing audio description text with start and end timestamps. Please note that the audio description is supposed to be centre aligned at the middle point between the start and the end times.
• Audio description audio - .wav file containing the audio track of the audio description. It has the same length as the input source media.
• Audio description audio with ducking applied - .wav file containing the audio track of the audio description with volume level ducking applied. It has the same length as the input source media.
• Proxy video with audio description audio mixed into the original audio - .mp4 file containing the original video in low resolution and the audio description mixed into the original audio.

If outputOptions.audioDescription.generateAdMixedInOriginal setting is set to true when creating the LEXI AD order, one more output will be generated:

• Original video with audio description audio mixed into the original audio - .mp4 file containing the original video in its original resolution and the audio description mixed into the original audio.

Optional outputs controlled by outputOptions.audioDescription flags include the source media transcript, metadata, and source media description files, omit flags to rely on documented defaults.

10. Supported Languages and Formats

Please note that the content in this chapter does not apply to LEXI AD. LEXI AD input language support is limited, and the output format options cannot be customized. For information about LEXI AD language support, see the Specifying languages and voices for LEXI AD section.

10.1. LEXI Recorded input and output languages

The input language is the language spoken in the source media.

Supported output languages depend on the input language specified. The output language could be written language matching the input, a specific locale of the written language matching the input, or a totally different written language supported by translation.

Below is the full list of supported languages and their language codes, which are used in API calls. There are 90 supported input languages:

10.2. LEXI Recorded additional translation languages

Additional translations can be requested by specifying the languages you want to be translated into from the "output" language. In such use case, normally you should let the "output" language be the same as the "input" language to avoid double translation.

The following are the 75 supported translation languages:

10.3. LEXI Recorded Output formats

Below are the supported output formats for captions:

Among them, srt and docx are always generated. If you need other formats to be generated, you can include them in the additionalOutputFormats field when creating the order.

10.4. LEXI AD output voices

The following voices are available for the LEXI AD product, grouped by supported language.

There are 56 languages with available voices for LEXI AD:

10.5. LEXI Voice for Recorded output voices

The following voices are available for the LEXI Voice for Recorded product, grouped by supported language.

There are 36 languages with available voices for LEXI Voice for Recorded: