--- type: api title: Create an JinaAI inference endpoint description: Create an inference endpoint to perform an inference task with the `jinaai` service. url: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/v8/operation/operation-inference-put-jinaai resource: https://www.elastic.co/elastic/docs-builder/docs/4641/api/doc/elasticsearch/v8/operation/operation-inference-put-jinaai products: - Elasticsearch --- # Create an JinaAI inference endpoint Authentication: required Availability: Generally available since 8.18 ## Paths - `PUT` `/_inference/{task_type}/{jinaai_inference_id}` #### Path parameters - `task_type` (enum) — required The type of the inference task that the model will perform. Values: `rerank`, `text_embedding` - `jinaai_inference_id` (string) — required The unique identifier of the inference endpoint. ## Description Create an inference endpoint to perform an inference task with the `jinaai` service. To review the available `rerank` models, refer to . To review the available `text_embedding` models, refer to the . ## Required authorization - Cluster privileges: `manage_inference` ## Query string parameters - `timeout` (string · default: 30s) — optional Specifies the amount of time to wait for the inference endpoint to be created. ## Request body `application/json` - `chunking_settings` (object) — 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) — required The type of service supported for the specified task type. In this case, `jinaai`. Values: `jinaai` - `service_settings` (object) — required Settings used to install the inference model. These settings are specific to the `jinaai` service. - `api_key` (string) — required A valid API key of your JinaAI account. IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. - `model_id` (string) — required The name of the model to use for the inference task. - `rate_limit` (object) — optional This setting helps to minimize the number of rate limit errors returned from JinaAI. By default, the `jinaai` service sets the number of requests allowed per minute to 2000 for all task types. - `requests_per_minute` (number) — optional The number of requests allowed per minute. - `similarity` (enum) — optional For a `text_embedding` task, the similarity measure. One of cosine, dot_product, l2_norm. The default values varies with the embedding type. For example, a float embedding type uses a `dot_product` similarity measure by default. Values: `cosine`, `dot_product`, `l2_norm` - `dimensions` (number) — optional For a `text_embedding` task, the number of dimensions the resulting output embeddings should have. By default, the model's standard output dimension is used. Refer to the Jina documentation for more information. - `embedding_type` (enum · default: float) — optional For a `text_embedding` task, the data type returned by the model. Use `bit` for binary embeddings, which are encoded as bytes with signed int8 precision. Use `binary` for binary embeddings, which are encoded as bytes with signed int8 precision (this is a synonym of `bit`). Use `float` for the default float embeddings. Values: `binary`, `bit`, `float` - `task_settings` (object) — optional Settings to configure the inference task. These settings are specific to the task type you specified. - `return_documents` (boolean) — optional For a `rerank` task, return the doc text within the results. - `task` (enum) — optional For a `text_embedding` task, the task passed to the model. Valid values are: * `classification`: Use it for embeddings passed through a text classifier. * `clustering`: Use it for the embeddings run through a clustering algorithm. * `ingest`: Use it for storing document embeddings in a vector database. * `search`: Use it for storing embeddings of search queries run against a vector database to find relevant documents. Values: `classification`, `clustering`, `ingest`, `search` - `top_n` (number) — optional For a `rerank` task, the number of most relevant documents to return. It defaults to the number of the documents. If this inference endpoint is used in a `text_similarity_reranker` retriever query and `top_n` is set, it must be greater than or equal to `rank_window_size` in the query. ## Response `application/json` - `chunking_settings` (object) 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` (object) Settings specific to the service - `task_settings` (object) Task settings specific to the service and task type - `inference_id` (string) The inference Id - `task_type` (enum) The task type Values: `text_embedding`, `rerank` ## Code examples ### A text embedding task #### Console ```console PUT _inference/text_embedding/jinaai-embeddings { "service": "jinaai", "service_settings": { "model_id": "jina-embeddings-v3", "api_key": "JinaAi-Api-key" } } ``` #### JavaScript ```javascript const response = await client.inference.put({ task_type: "text_embedding", inference_id: "jinaai-embeddings", inference_config: { service: "jinaai", service_settings: { model_id: "jina-embeddings-v3", api_key: "JinaAi-Api-key", }, }, }); ``` #### Python ```python resp = client.inference.put( task_type="text_embedding", inference_id="jinaai-embeddings", inference_config={ "service": "jinaai", "service_settings": { "model_id": "jina-embeddings-v3", "api_key": "JinaAi-Api-key" } }, ) ``` #### curl ```curl curl -X PUT "$ELASTICSEARCH_URL/_inference/text_embedding/jinaai-embeddings" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "jinaai", "service_settings": { "model_id": "jina-embeddings-v3", "api_key": "JinaAi-Api-key" } }' ``` #### Java ```java client.inference().put(p -> p .inferenceId("jinaai-embeddings") .taskType(TaskType.TextEmbedding) .inferenceConfig(i -> i .service("jinaai") .serviceSettings(JsonData.fromJson("{\"model_id\":\"jina-embeddings-v3\",\"api_key\":\"JinaAi-Api-key\"}")) ) ); ``` #### C# ```c# var response = await client.Inference .PutAsync(new PutInferenceRequest() { InferenceId = "jinaai-embeddings", TaskType = TaskType.TextEmbedding, InferenceConfig = new() { Service = "jinaai", ServiceSettings = JsonSerializer.Deserialize(""" { "model_id": "jina-embeddings-v3", "api_key": "JinaAi-Api-key" } """) } }); ``` #### PHP ```php $resp = $client->inference()->put([ "task_type" => "text_embedding", "inference_id" => "jinaai-embeddings", "body" => [ "service" => "jinaai", "service_settings" => [ "model_id" => "jina-embeddings-v3", "api_key" => "JinaAi-Api-key", ], ], ]); ``` #### Ruby ```ruby response = client.inference.put( task_type: "text_embedding", inference_id: "jinaai-embeddings", body: { "service": "jinaai", "service_settings": { "model_id": "jina-embeddings-v3", "api_key": "JinaAi-Api-key" } } ) ``` ### A rerank task #### Console ```console PUT _inference/rerank/jinaai-rerank { "service": "jinaai", "service_settings": { "api_key": "JinaAI-Api-key", "model_id": "jina-reranker-v2-base-multilingual" }, "task_settings": { "top_n": 10, "return_documents": true } } ``` #### JavaScript ```javascript const response = await client.inference.put({ task_type: "rerank", inference_id: "jinaai-rerank", inference_config: { service: "jinaai", service_settings: { api_key: "JinaAI-Api-key", model_id: "jina-reranker-v2-base-multilingual", }, task_settings: { top_n: 10, return_documents: true, }, }, }); ``` #### Python ```python resp = client.inference.put( task_type="rerank", inference_id="jinaai-rerank", inference_config={ "service": "jinaai", "service_settings": { "api_key": "JinaAI-Api-key", "model_id": "jina-reranker-v2-base-multilingual" }, "task_settings": { "top_n": 10, "return_documents": True } }, ) ``` #### curl ```curl curl -X PUT "$ELASTICSEARCH_URL/_inference/rerank/jinaai-rerank" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "service": "jinaai", "service_settings": { "api_key": "JinaAI-Api-key", "model_id": "jina-reranker-v2-base-multilingual" }, "task_settings": { "top_n": 10, "return_documents": true } }' ``` #### Java ```java client.inference().put(p -> p .inferenceId("jinaai-rerank") .taskType(TaskType.Rerank) .inferenceConfig(i -> i .service("jinaai") .serviceSettings(JsonData.fromJson("{\"api_key\":\"JinaAI-Api-key\",\"model_id\":\"jina-reranker-v2-base-multilingual\"}")) .taskSettings(JsonData.fromJson("{\"top_n\":10,\"return_documents\":true}")) ) ); ``` #### C# ```c# var response = await client.Inference .PutAsync(new PutInferenceRequest() { InferenceId = "jinaai-rerank", TaskType = TaskType.Rerank, InferenceConfig = new() { Service = "jinaai", ServiceSettings = JsonSerializer.Deserialize(""" { "api_key": "JinaAI-Api-key", "model_id": "jina-reranker-v2-base-multilingual" } """), TaskSettings = JsonSerializer.Deserialize(""" { "top_n": 10, "return_documents": true } """) } }); ``` #### PHP ```php $resp = $client->inference()->put([ "task_type" => "rerank", "inference_id" => "jinaai-rerank", "body" => [ "service" => "jinaai", "service_settings" => [ "api_key" => "JinaAI-Api-key", "model_id" => "jina-reranker-v2-base-multilingual", ], "task_settings" => [ "top_n" => 10, "return_documents" => true, ], ], ]); ``` #### Ruby ```ruby response = client.inference.put( task_type: "rerank", inference_id: "jinaai-rerank", body: { "service": "jinaai", "service_settings": { "api_key": "JinaAI-Api-key", "model_id": "jina-reranker-v2-base-multilingual" }, "task_settings": { "top_n": 10, "return_documents": true } } ) ``` ## Response examples #### 200 `application/json` Generated from the API spec. Values are representative. Unions use the first variant; deeply nested or large bodies may omit fields. ```json { "chunking_settings": { "max_chunk_size": 250, "overlap": 100, "sentence_overlap": 1, "strategy": "sentence" }, "service": "string", "service_settings": {}, "task_settings": {}, "inference_id": "string", "task_type": "text_embedding" } ```