Embeddings

Generate vector embeddings optimized for medical text.

POST https://api.persly.ai/v1/embeddings

Creates embedding vectors for the given input text. The embeddings are 768-dimensional vectors optimized for medical text similarity and retrieval tasks.

Request Body

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	Must be `persly-embed-v1`
`input`	string \| string[]	Yes	—	Text to embed. Single string or array of up to 100 strings.
`encoding_format`	string	No	`"float"`	Output format. Only `"float"` is supported.

Response Body

Field	Type	Description
`id`	string	Unique request ID in `emb_{hex}` format
`object`	string	Always `"list"`
`created`	integer	Unix timestamp
`model`	string	`"persly-embed-v1"`
`data`	array	Array of embedding objects
`data[].object`	string	Always `"embedding"`
`data[].index`	integer	Index corresponding to the input array position
`data[].embedding`	number[]	768-dimensional embedding vector
`usage`	object	Token usage information
`usage.prompt_tokens`	integer	Number of input tokens processed
`usage.total_tokens`	integer	Total tokens (same as `prompt_tokens` for embeddings)

Examples

Single Text

curl https://api.persly.ai/v1/embeddings \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "persly-embed-v1",
    "input": "Symptoms of acute myocardial infarction include chest pain, dyspnea, and diaphoresis."
  }'

import requests

response = requests.post(
    "https://api.persly.ai/v1/embeddings",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "persly-embed-v1",
        "input": "Symptoms of acute myocardial infarction include chest pain, dyspnea, and diaphoresis.",
    },
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Dimensions: {len(embedding)}")  # 768
print(f"Tokens used: {data['usage']['prompt_tokens']}")

const response = await fetch("https://api.persly.ai/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "persly-embed-v1",
    input:
      "Symptoms of acute myocardial infarction include chest pain, dyspnea, and diaphoresis.",
  }),
});

const data = await response.json();
const embedding = data.data[0].embedding;
console.log(`Dimensions: ${embedding.length}`); // 768
console.log(`Tokens used: ${data.usage.prompt_tokens}`);

Response

{
  "id": "emb_a1b2c3d4e5f6a1b2c3d4e5f6",
  "object": "list",
  "created": 1709000000,
  "model": "persly-embed-v1",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, 0.015797347, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}

Batch Request

Embed multiple texts in a single request (up to 100 items):

curl https://api.persly.ai/v1/embeddings \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "persly-embed-v1",
    "input": [
      "Patient presents with chest pain radiating to left arm.",
      "Blood glucose level of 250 mg/dL indicates hyperglycemia.",
      "MRI shows herniated disc at L4-L5 level."
    ]
  }'

Batch response

{
  "id": "emb_...",
  "object": "list",
  "created": 1709000000,
  "model": "persly-embed-v1",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.002, -0.009, ...]},
    {"object": "embedding", "index": 1, "embedding": [0.011, 0.003, ...]},
    {"object": "embedding", "index": 2, "embedding": [-0.005, 0.012, ...]}
  ],
  "usage": {
    "prompt_tokens": 42,
    "total_tokens": 42
  }
}

Errors

Status	Code	Cause
400	`model_not_found`	Invalid model (must be `persly-embed-v1`)
400	`invalid_request`	Invalid `encoding_format` or empty input strings
400	`batch_size_exceeded`	Batch contains more than 100 items
401	`authentication_error`	Invalid API key
429	`quota_exceeded`	Free credits exhausted
429	`spending_limit_exceeded`	Monthly spending limit reached