---
title: "Create embeddings"
method: POST
path: "/v1/projects/{project_id}/embeddings"
tags: ["Embeddings"]
---

# Create embeddings

`POST /v1/projects/{project_id}/embeddings`

## Request

- Base URL: `https://api.naturali.ai`
- URL: `https://api.naturali.ai/v1/projects/{project_id}/embeddings`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.naturali.ai/authorize`, token URL `https://api.naturali.ai/token`, scopes: `mcp:access`)

Generates embedding vectors for one or more text inputs using the server's configured embedding model.
Provide `input` for a single text or `inputs` for a batch. At least one is required.
Returns `embedding` when `input` is used, and `embeddings` when `inputs` is used.

`project_id` names the project the call's token usage is metered against, so
embedding spend reaches the usage rollup and the project's `cost_usd` / `tokens`
quotas. A project-scoped credential supplies its own project; a call that names
none and is bound to none is `400 VALIDATION_FAILED`.

## Request body

- object
  - `input` string: Single text to embed.
  - `inputs` string[]: 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.

## Response `200`

Embeddings generated successfully

- EmbeddingsResponse: Response containing generated embeddings. Fields present depend on whether `input` or `inputs` was provided.
  - `embedding` number[]: Embedding vector for the single `input` text.
  - `embeddings` array[]: Embedding vectors for each item in the `inputs` batch.
    - number[]

## Other responses

- `400`: Invalid request body, or no project to bill (no `project_id` and a credential bound to none)
- `401`: Unauthorized
- `403`: The caller cannot write to the named `project_id`
- `503`: Embedding service not configured

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)