--- type: api title: Create a VoyageAI inference endpoint description: Create an inference endpoint to perform an inference task with the `voyageai` service. url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-inference-put-voyageai resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/operation/operation-inference-put-voyageai products: - Elasticsearch --- # Create a VoyageAI inference endpoint Availability: 8.19+ ## Paths - `PUT` `/_inference/{task_type}/{voyageai_inference_id}` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v8/authentication#bearerauth) #### Path Parameters - `task_type` (enum VoyageAITaskType) The type of the inference task that the model will perform. Values: `text_embedding`, `rerank` - `voyageai_inference_id` (string Id) The unique identifier of the inference endpoint. ## Description Create an inference endpoint to perform an inference task with the `voyageai` service. Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources. ## Required authorization * Cluster privileges: `manage_inference` ## Query String Parameters - `timeout` (string Duration · default: 30s) Specifies the amount of time to wait for the inference endpoint to be created. ## Request Body `application/json` - `chunking_settings` ({} InferenceChunkingSettings) — optional The chunking configuration object. - `max_chunk_size` (number · default: 250) — optional The maximum size of a chunk in words. This value cannot be higher than `300` or lower than `20` (for `sentence` strategy) or `10` (for `word` strategy). - `overlap` (number · default: 100) — optional The number of overlapping words for chunks. It is applicable only to a `word` chunking strategy. This value cannot be higher than half the `max_chunk_size` value. - `sentence_overlap` (number · default: 1) — optional The number of overlapping sentences for chunks. It is applicable only for a `sentence` chunking strategy. It can be either `1` or `0`. - `strategy` (string · default: sentence) — optional The chunking strategy: `sentence` or `word`. - `service` (enum VoyageAIServiceType) — required The type of service supported for the specified task type. In this case, `voyageai`. Values: `voyageai` - `service_settings` ({} VoyageAIServiceSettings) — required Settings used to install the inference model. These settings are specific to the `voyageai` service. - `dimensions` (number) — optional The number of dimensions for resulting output embeddings. This setting maps to `output_dimension` in the VoyageAI documentation. Only for the `text_embedding` task type. - `model_id` (string) — required The name of the model to use for the inference task. Refer to the VoyageAI documentation for the list of available text embedding and rerank models. - `rate_limit` ({} RateLimitSetting) — optional This setting helps to minimize the number of rate limit errors returned from VoyageAI. The `voyageai` service sets a default number of requests allowed per minute depending on the task type. For both `text_embedding` and `rerank`, it is set to `2000`. - `requests_per_minute` (number) — optional The number of requests allowed per minute. - `embedding_type` (number) — optional The data type for the embeddings to be returned. This setting maps to `output_dtype` in the VoyageAI documentation. Permitted values: float, int8, bit. `int8` is a synonym of `byte` in the VoyageAI documentation. `bit` is a synonym of `binary` in the VoyageAI documentation. Only for the `text_embedding` task type. - `task_settings` ({} VoyageAITaskSettings) — optional Settings to configure the inference task. These settings are specific to the task type you specified. - `input_type` (string) — optional Type of the input text. Permitted values: `ingest` (maps to `document` in the VoyageAI documentation), `search` (maps to `query` in the VoyageAI documentation). Only for the `text_embedding` task type. - `return_documents` (boolean · default: false) — optional Whether to return the source documents in the response. Only for the `rerank` task type. - `top_k` (number) — optional The number of most relevant documents to return. If not specified, the reranking results of all documents will be returned. Only for the `rerank` task type. - `truncation` (boolean · default: true) — optional Whether to truncate the input texts to fit within the context length. ## Response `application/json` - `chunking_settings` ({} InferenceChunkingSettings) Chunking configuration object - `max_chunk_size` (number · default: 250) The maximum size of a chunk in words. This value cannot be higher than `300` or lower than `20` (for `sentence` strategy) or `10` (for `word` strategy). - `overlap` (number · default: 100) The number of overlapping words for chunks. It is applicable only to a `word` chunking strategy. This value cannot be higher than half the `max_chunk_size` value. - `sentence_overlap` (number · default: 1) The number of overlapping sentences for chunks. It is applicable only for a `sentence` chunking strategy. It can be either `1` or `0`. - `strategy` (string · default: sentence) The chunking strategy: `sentence` or `word`. - `service` (string) The service type - `service_settings` (ServiceSettings) Settings specific to the service - `task_settings` (TaskSettings) Task settings specific to the service and task type - `inference_id` (string) The inference Id - `task_type` (enum TaskTypeVoyageAI) The task type Values: `text_embedding`, `rerank` ## Code Examples #### Console ```console PUT _inference/text_embedding/openai-embeddings { "service": "voyageai", "service_settings": { "model_id": "voyage-3-large", "dimensions": 512 } } ``` #### JavaScript ```javascript const response = await client.inference.put({ task_type: "text_embedding", inference_id: "openai-embeddings", inference_config: { service: "voyageai", service_settings: { model_id: "voyage-3-large", dimensions: 512, }, }, }); ``` #### Python ```python resp = client.inference.put( task_type="text_embedding", inference_id="openai-embeddings", inference_config={ "service": "voyageai", "service_settings": { "model_id": "voyage-3-large", "dimensions": 512 } }, ) ``` #### curl ```curl curl -X PUT "$ELASTICSEARCH_URL/_inference/text_embedding/openai-embeddings" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "voyageai", "service_settings": { "model_id": "voyage-3-large", "dimensions": 512 } }' ``` #### Java ```java client.inference().put(p -> p .inferenceId("openai-embeddings") .taskType(TaskType.TextEmbedding) .inferenceConfig(i -> i .service("voyageai") .serviceSettings(JsonData.fromJson("{\"model_id\":\"voyage-3-large\",\"dimensions\":512}")) ) ); ``` #### C# ```c# var response = await client.Inference .PutAsync(new PutInferenceRequest() { InferenceId = "openai-embeddings", TaskType = TaskType.TextEmbedding, InferenceConfig = new() { Service = "voyageai", ServiceSettings = JsonSerializer.Deserialize(""" { "model_id": "voyage-3-large", "dimensions": 512 } """) } }); ``` #### PHP ```php $resp = $client->inference()->put([ "task_type" => "text_embedding", "inference_id" => "openai-embeddings", "body" => [ "service" => "voyageai", "service_settings" => [ "model_id" => "voyage-3-large", "dimensions" => 512, ], ], ]); ``` #### Ruby ```ruby response = client.inference.put( task_type: "text_embedding", inference_id: "openai-embeddings", body: { "service": "voyageai", "service_settings": { "model_id": "voyage-3-large", "dimensions": 512 } } ) ```