Embeddings

POST /v1/embeddings  compatible  semantic operation embed  contract revision 1

State semantics: stateless

Raw contract deviations

These statements are source-contract evidence. Use the examples, field table, and Profile coverage matrix for ordinary integration, and expand this list when investigating a compatibility boundary.

• gateway routes model names
• unknown request fields are rejected before provider I/O
• provider-specific unsupported fields are rejected before provider I/O

Request examples

curl

curl https://halro.example.com/v1/embeddings \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "embed", "input": ["first passage", "second passage"] }'

Python

import os
from openai import OpenAI

client = OpenAI(base_url="https://halro.example.com/v1", api_key=os.environ["HALRO_GATEWAY_KEY"],
                timeout=60.0, max_retries=0)
response = client.embeddings.create(model="embed", input=["first passage", "second passage"])
print(len(response.data), "vectors, dimension", len(response.data[0].embedding))

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://halro.example.com/v1", apiKey: process.env.HALRO_GATEWAY_KEY,
  timeout: 60_000, maxRetries: 0,
});
const response = await client.embeddings.create({
  model: "embed", input: ["first passage", "second passage"],
});
console.log(response.data.length, "vectors, dimension", response.data[0].embedding.length);

SDK retries are enabled by default

Official SDKs normally retry twice. Halro persists the budget reservation before Provider I/O, so a silent client retry creates separate reservations and settlements. The examples disable SDK retries; own the retry policy using Retries, timeouts, and idempotency.

Request headers

• Authorization
• Content-Type

Request fields

How to read this table

Silence in column two does not mean verified support. The contract records declared limits; a Profile with no listed restriction remains undeclared, not proven compatible. Column three records value- or combination-level rejections that cannot be represented by a field-only matrix. Types, required relationships, and value semantics are not yet carried by this contract.

Request fields

Field	Provider Profiles that do not support it	Combination-level constraints
model	—	—
input	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
encoding_format	gemini.generate-content.text.v1beta, bedrock.runtime.invoke.titan-embed-text-v2.v1	—
dimensions	bedrock.runtime.invoke.titan-embed-text-v2.v1	—
user	gemini.generate-content.text.v1beta, bedrock.runtime.invoke.titan-embed-text-v2.v1	—

Response fields

object data model usage

Provider Profile contract coverage and current availability

Endpoint maturity does not promote a Profile

The compatible badge describes the endpoint. Every Profile row retains its own coverage maturity.

Maturity divergence

bedrock.runtime.invoke.titan-embed-text-v2.v1 is experimental, below endpoint maturity compatible.

A contract does not mean this build can create it

bedrock.runtime.invoke.titan-embed-text-v2.v1 remain in the compatibility contract but are withheld by the served Profile matrix at Halro 8f185de7674c. The Admin write path rejects new Deployments for them; existing records retain only startup and deletion paths.

Provider Profile contract coverage and current availability

Provider Profile	Maturity	Current build	Unsupported request fields
openai.chat-embeddings.v1	compatible	creatable	undeclared
azure-openai.chat-embeddings.v1	compatible	creatable	undeclared
openai-compatible.chat-embeddings.v1	compatible	creatable	undeclared
gemini.generate-content.text.v1beta	compatible	creatable	encoding_format, user
bedrock.runtime.invoke.titan-embed-text-v2.v1	experimental	withheld (cannot create)	input, encoding_format, dimensions, user

Declared transformations

gemini.generate-content.text.v1beta

• token usage is locally estimated when Gemini omits usage

bedrock.runtime.invoke.titan-embed-text-v2.v1

• only one string input is accepted
• dimensions are limited to 256, 512, or 1024
• native requests force normalized float embeddings
• Bedrock inputTextTokenCount is mapped to OpenAI usage

Evidence

Verified evidence: gateway_contract, provider_transport_fixture, sdk_blackbox

SDK black-box protocol-stub matrix

openai-go, openai-node, openai-python

Caution

This matrix proves that listed SDK versions serialize requests and consume Halro’s declared response and stream shapes. It uses protocol stubs and does not exercise live Runtime routing, Gateway Key authentication, capability filtering, redaction, budget accounting, or a real Provider.

Best practices

See Embedding index and Rerank planning.

---

Fields, coverage, transformations, and deviations are generated from Halro 8f185de7674c (scripts/generate-api-pages-en.mjs; synchronized manifest digest 8e5e7a0a794721aa…). The synchronized copy contains 1 recorded accuracy correction(s); source manifest digest b321ee18ad2e38f3…. The contract currently carries field names, not complete types, required relationships, or value semantics.