Get Started

Migration guide

Follow the instructions in this guide to update your application from Marengo 2.7 to Marengo 3.0. For a list of new features and improvements in the latest version, see the New in Marengo 3.0 section.

Migration steps

If your application uses Marengo 2.7, follow these steps to migrate to Marengo 3.0:

1

Review the changes

Read the sections below to understand what changed.

2

Update your SDK

Install the latest version of the Python or Node.js SDK.

3

Update your code

Update your search, indexing, and embeddings code.

Migration overview

Both Marengo 3.0 and Marengo 2.7 are available and you can specify them when creating indexes or embeddings. TwelveLabs will automatically reindex your videos created with Marengo 2.7 at a date that will be announced later. After the reindexing is complete, Marengo 2.7 will be deprecated, and all requests specifying Marengo 2.7 will map to Marengo 3.0.

To use the new version, update the version strings in your code as follows:

FeatureMarengo 2.7 valueMarengo 3.0 value
Indexesmarengo2.7marengo3.0
Embeddingsmarengo-retrieval-2.7marengo3.0

Marengo 3.0 introduces changes across the following categories:

  • API-compatible changes (no errors, but logic updates required):

    • Deprecated search parameters now are ingored by the platform
    • Audio processing separates speech from non-speech content

    Your code will not throw errors, but you must update your application logic to maintain functionality.

  • Breaking changes (required action):

    • The Embed API has breaking changes with incompatible results

The sections below detail each change and the actions you must take.

Changes that require logic updates

Make search requests

MethodDescriptionAction
POST /searchThe adjust_confidence_level, sort_option, and threshold parameters and are deprecated in Marengo 3.0Update your logic use the rank field in the response instead.
POST /searchThe score and confidence fields in the response and are deprecated in Marengo 3.0Update your logic use the rank field in the response instead.
POST /searchThe audio search option now processes only non-speech audio (music, sound effects, environmental sounds).If you search for spoken content, set search_options to transcription instead of audio. Using audio for spoken content returns incomplete results.
POST /searchYou can now search for spoken words using the transcription search option.Set search_options to transcription in your search requests.
POST /searchYou can now control how the platform matches your query against spoken words.Set transcription_options to lexical for exact word matching, semantic for meaning-based matching, or both for comprehensive results.

For details about how search options work, see the Search options section.

For a complete guide on making search requests, see the Search page.

Breaking changes

These changes require immediate action from you.

Create embeddings

MethodDescriptionRequired action
- POST /embed/tasks
- POST /embed		The embeddings types and dimensions are not compatible with Marengo 2.7.You must regenerate all your text, audio, image, and video embeddings with Marengo 3.0.

Create video embeddings

MethodDescriptionRequired action
GET /embed/tasks/{task_id}The visual-text value has been renamed.Set embedding_option to visual instead of visual-text.
GET /embed/tasks/{task_id}The audio embedding option now processes only non-verbal audio.If you need embeddings for spoken content, set the embedding_option parameter to transcription.

For a complete example of creating embeddings with Marengo 3.0, see the Create video embeddings page.

For details about embedding options, see the Embedding options section.

Additional resources

Python SDK Reference
Node.js SDK Reference
API Reference
Discord