API reference

Services.

Translation, text from images, speech to text and embeddings. Each is a separate service with its own endpoint. Embeddings use a fixed engine for your search index.

You call the service's endpointSame base URL and API key as chat. Any key can use every service.

Ompera picks a free providerOnly providers that turned the service on, and passed Ompera's test request for it, receive requests.

An engine made for the task answersNever a chat model. For embeddings, the model field selects a fixed engine; other services ignore it.

GET/v1/capabilities

Availability

Which services have a provider online right now.

Example

curl https://api.ompera.net/v1/capabilities \
  -H "Authorization: Bearer $OMPERA_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "translation",
      "object": "capability",
      "name": "Translation",
      "endpoint": "/v1/translations",
      "available_nodes": 3,
      "capacity": 3,
      "inflight": 1
    }
  ]
}

The embeddings entry also includes engines: each available engine’s id, name and capacity. Save one ID for your search index and use it for both documents and queries. Changing engines requires reindexing.

One entry per service: translation, ocr, speech_to_text and embeddings. available_nodes is how many providers offer it now; with 0, a request gets provider_unavailable.

POST/v1/translations

Translation

Translates text between about 60 languages. One non-streaming result.

Request

Field	Notes
`input`required	The text, up to 4 KiB.
`target_language`required	A language code such as `en`, `de`, `uk` or `pt-BR`.
`source_language`	The language of `input`. Detected when omitted.

Example

curl

curl https://api.ompera.net/v1/translations \
  -H "Authorization: Bearer $OMPERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Hello, world!","source_language":"en","target_language":"fr"}'

Python

import os
import requests

reply = requests.post(
    "https://api.ompera.net/v1/translations",
    headers={"Authorization": f"Bearer {os.environ['OMPERA_API_KEY']}"},
    json={"input": "Hello, world!", "target_language": "fr"},
    timeout=300,
)
reply.raise_for_status()
print(reply.json()["text"])

Response

{
  "object": "translation",
  "text": "Bonjour le monde !",
  "source_language": "en",
  "target_language": "fr"
}

POST/v1/ocr

Text from images

Reads Ukrainian and English text from a photo, scan or screenshot.

Request

Field	Notes
`image_base64`required	The image, base64-encoded, up to 23 MiB. Send it as JSON.

Example

curl

curl https://api.ompera.net/v1/ocr \
  -H "Authorization: Bearer $OMPERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"image_base64\":\"$(base64 < page.png | tr -d '\n')\"}"

Python

import base64, os
import requests

with open("page.png", "rb") as image:
    encoded = base64.b64encode(image.read()).decode()
reply = requests.post(
    "https://api.ompera.net/v1/ocr",
    headers={"Authorization": f"Bearer {os.environ['OMPERA_API_KEY']}"},
    json={"image_base64": encoded},
    timeout=300,
)
reply.raise_for_status()
print(reply.json()["text"])

Response

{"text": "Invoice No. 1042\nTotal: 120.00 EUR", "confidence": 0.93}

POST/v1/audio/transcriptions

Speech to text

Turns a recording into text in 99 languages, or translates the speech into English. Multipart form data, as with the OpenAI API.

Request

Field	Notes
`file`required	A WAV, MP3 or FLAC recording, up to 23 MiB.
`language`	The spoken language, such as `en`. Detected when omitted.
`response_format`	`json` (default) or `text`.
`translate`	`true` returns the speech translated into English.

Example

curl

curl https://api.ompera.net/v1/audio/transcriptions \
  -H "Authorization: Bearer $OMPERA_API_KEY" \
  -F [email protected]

Python

The OpenAI SDK requires a model argument: pass any value, it is ignored.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ompera.net/v1", api_key=os.environ["OMPERA_API_KEY"])
with open("recording.wav", "rb") as audio:
    result = client.audio.transcriptions.create(model="ompera", file=audio)
print(result.text)

Response

{"text": "Hello, this is a test recording.", "language": "en", "duration": 2.4}

POST/v1/embeddings

Embeddings

Turns text into vectors for search and RAG. EmbeddingGemma 2 supports multilingual input and 128, 256, 512 or 768 dimensions; MiniLM uses 384 dimensions and works best for English. Choose an available engine from Availability. Text input only, in OpenAI format.

Request

Field	Notes
`model`	The exact embedding engine ID from `/v1/capabilities` → `engines`. Required when more than one engine is available. An unavailable engine returns an error; no automatic engine change.
`input_type`	For EmbeddingGemma 2: `document` (default) to index text, or `query` to search. The engine adds its required prefix; send plain text.
`input`required	A string, or up to 64 strings; 64 KiB in total. For EmbeddingGemma 2, each text is at most 32 KB. Split long documents into chunks.

Example

curl

curl https://api.ompera.net/v1/embeddings \
  -H "Authorization: Bearer $OMPERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$OMPERA_EMBEDDING_ENGINE\",\"input\":[\"Ompera routes requests to providers.\",\"Pools share models.\"]}"

Python

Set OMPERA_EMBEDDING_ENGINE to the exact engine ID you saved for your index.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ompera.net/v1", api_key=os.environ["OMPERA_API_KEY"])
result = client.embeddings.create(model=os.environ["OMPERA_EMBEDDING_ENGINE"], input=["first text", "second text"])
print(len(result.data[0].embedding))  # depends on the selected engine

Response

{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0213, -0.0472, 0.0891, …]},
    {"object": "embedding", "index": 1, "embedding": [-0.0154, 0.0337, 0.0602, …]}
  ]
}