Guides
HomeDocumentationBlogAbout

API Key and Python Client

Suggest Edits

Authentication with API Keys

Voyage AI utilizes API keys to monitor usage and manage permissions. To obtain your key, please sign in with your Voyage AI account and click the "Create new API key" button in the dashboard. We recommend setting the API key as an environment variable. For example, in MacOS or Linux, type the following command in the terminal, replacing <your secret key> with your actual API key:

export VOYAGE_API_KEY="<your secret key>"

You can verify the setup by typing echo $VOYAGE_API_KEY in the terminal. It should display your API key.

Your API key is supposed to be secret -- please avoid sharing it or exposing it in browsers or apps. Please store your API key securely for future use.

Install Voyage Python Package

You can interact with the API through HTTP requests from any language. For Python users, we offer an official package which can be installed via pip :

pip install -U voyageai

We recommend using the -U or --upgrade option to ensure you are installing the latest version of the package. This helps you access the most recent features and bug fixes.

After installation, you can test it by running:

python -c "import voyageai"

The installation is successful if this command runs without any errors.

voyageai.Client

The Python package offers the voyageai.Client class as the interface to invoke Voyage's API. You can create a client object and use it to access the predictions by our models.

class voyageai.Client

Parameters

  • api_key (str, optional, defaults to None) - Voyage API key. If None, the client will search for the API key in the following order:
    • voyageai.api_key_path, path to the file containing the key;
    • environment variable VOYAGE_API_KEY_PATH, which can be set to the path to the file containing the key;
    • voyageai.api_key, an attribute of the voyageai module, which can be used to store the key;
    • environment variable VOYAGE_API_KEY.
  • max_retries (int, defaults to 0) - Maximum number of retries for each API request in case of rate limit errors or temporary server unavailability. The client employs a wait-and-retry strategy to handle such errors, and will raise an exception upon reaching the maximum retry limit. By default, the client does not retry.
  • timeout (int, optional, defaults to None) - Maximum time in seconds to wait for a response from the API before aborting the request. If the specified timeout is exceeded, the request is terminated and a timeout exception is raised. By default, no timeout constraint is enforced.

Example

import voyageai

vo = voyageai.Client()
# This will automatically use the environment variable VOYAGE_API_KEY.
# Alternatively, you can use vo = voyageai.Client(api_key="<your secret key>")

result = vo.embed(["hello world"], model="voyage-3")

voyageai.AsyncClient

The Python package provides a voyageai.AsyncClient class designed for asynchronous API calls. This AsyncClient class mirrors the Client class in terms of method offerings and input/output specifications but is tailored for asynchronous operations, enabling non-blocking API requests.

Example

import voyageai

vo = voyageai.AsyncClient()
# This will automatically use the environment variable VOYAGE_API_KEY.
# Alternatively, you can use vo = voyageai.AsyncClient(api_key="<your secret key>")

result = await vo.embed(["hello world"], model="voyage-3")

Updated 3 months ago