Skip to main content

Embeddings

Text in, vectors out — the same computation ingestion and knowledge search run internally.

Overview​

POST /v1/projects/{project_id}/embeddings embeds one string or a batch of them with this API's embedding model, and returns the raw vectors. There is nothing else in this module.

You do not need it to use knowledge search — that embeds your query for you. It earns its place when you are building an index somewhere else and want the vectors to be comparable with the ones in this project, or when you want to compare two pieces of text directly without storing either.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Embeddings.

Data Model​

Request​

FieldTypeDescription
inputstringSingle text to embed. An empty string is 400 VALIDATION_FAILED.
inputsstring[]Batch of texts to embed. At most 256 per request — each input is one call to the embedding model, so a larger batch is refused (VALIDATION_FAILED) rather than queued. Split it across requests.

At least one of the two is required.

EmbeddingsResponse​

FieldTypeDescription
embeddingnumber[]Embedding vector for the single input text.
embeddingsarray of number[]Embedding vectors for each item in the inputs batch.

embedding is present when input was sent; embeddings, one vector per item in inputs and in that order, when inputs was.

Key Concepts​

Which field you send decides which you get back​

input answers embedding; inputs answers embeddings. The response shape follows the request, so a client that sometimes batches has to read both keys — or always send inputs, even for one string, and always read embeddings.

Batching is also the cheaper call: one round trip and one provider request for the whole list, rather than one each.

One embedding model serves every project​

Every embedding — this route, ingestion, memory writes, knowledge search — is made by this API's own embedding model, titan-text-embeddings-v2, whatever AI providers the project has: 1024-dimension vectors, the same for every project. You do not configure it, and no provider you register is used for it. Vectors from another model are not comparable with these.

Embedding spend is metered​

An embedding call's token usage is recorded against the project in the path, so it reaches that project's GET /v1/projects/{project_id}/usage rollup and counts towards its tokens and cost_usd quotas. Batching changes the round trips, not the total: the meter follows tokens.

Every embedding a project makes — this route, ingestion, memory writes, knowledge search — is paid from the credit balance, on every plan and whatever provider you generate with. While the balance is negative, writes that embed answer 402 INSUFFICIENT_CREDIT; knowledge search does not. This holds however the write arrives: a call to this API or an agent's tool call.

The project is always the one in the path; a project_id in the body that names another project is refused.

Who may do what​

Embedding needs any project member.

Examples​

Embed one string​

naturali create-embeddings \
--project-id proj_V1StGXR8Z5jdHi6B \
--input "Refunds are issued within 5 business days."

Embed a batch​

naturali create-embeddings \
--project-id proj_V1StGXR8Z5jdHi6B \
--inputs "First paragraph." \
--inputs "Second paragraph."