Python Quick Start Guide for v1-embeddings API

Last updated January 24, 2025

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

The Heroku Managed Inference and Agent add-on is currently in pilot. The products offered as part of the pilot aren’t intended for production use and are considered as a Beta Service and are subject to the Beta Services terms at https://www.salesforce.com/company/legal/agreements.jsp.

The Cohere Embed Multilingual (cohere-embed-multilingual) model generates vector embeddings (lists of numbers) for provided text inputs. These embeddings can be used in various applications, such as search, classification, and clustering. This guide details how to access the v1-embeddings API using Python.

Prerequisites

Before making requests, provision access to the model of your choice.

  1. If it’s not already installed, install the Heroku CLI. Then install the Heroku AI plugin:

    heroku plugins:install @heroku/plugin-ai

  2. Attach the embedding model to an app of yours:

    # If you don't have an app yet, you can create one with:
heroku create $APP_NAME # specify the name you want for your app (or skip this step to use an existing app you have)

# Create and attach one of our chat models to your app, $APP_NAME:

heroku ai:models:create -a $APP_NAME cohere-multilingual --as EMBEDDING

  3. Install the necessary requests package:

    pip install requests

Python Example Code

import requests
import json
import os

# Global variables for API endpoint, authorization key, and model ID from Heroku config variables
ENV_VARS = {
    "EMBEDDING_URL": None,
    "EMBEDDING_KEY": None,
    "EMBEDDING_MODEL_ID": None
}

# Assert the existence of required environment variables, with helpful messages if they're missing.
for env_var in ENV_VARS.keys():
    value = os.environ.get(env_var)
    assert value is not None, (
        f"Environment variable '{env_var}' is missing. Set it using:\n"
        f"export {env_var}=$(heroku config:get -a $APP_NAME {env_var})"
    )
    ENV_VARS[env_var] = value


def parse_embedding_output(response):
    """
    Parses and prints the API response for the embedding request.

    Parameters:
        - response (requests.Response): The response object from the API call.
    """
    if response.status_code == 200:
        result = response.json()
        print("Embeddings:", result["data"])
    else:
        print(f"Request failed: {response.status_code}, {response.text}")

def generate_embeddings(payload):
    """
    Generates embeddings using the Stability AI Embeddings model.

    Parameters:
        - payload (dict): dictionary containing parameters for the embedding generation

    Returns:
        - Prints the generated embeddings.
    """
    # Set headers using the global API key
    HEADERS = {
        "Authorization": f"Bearer {ENV_VARS['EMBEDDING_KEY']}",
        "Content-Type": "application/json"
    }
    endpoint_url = ENV_VARS['EMBEDDING_URL'] + "/v1/embeddings"
    response = requests.post(endpoint_url, headers=HEADERS, data=json.dumps(payload))

    parse_embedding_output(response=response)


# Example payload
payload = {
    "model": ENV_VARS["EMBEDDING_MODEL_ID"],
    "input": ["Hello, I am a blob of text.", "How's the weather in Portland?"],
    "input_type": "search_document",
    "truncate": "END",
    "encoding_format": "float"
}

# Generate embeddings with the given payload
generate_embeddings(payload)

Feedback

Log in to submit feedback.