# Create embeddings

URL: https://docs.hanzo.ai/docs/openapi/ai/post-embeddings

> Implements POST /v1/embeddings (OpenAI-compatible).

`POST /v1/embeddings`

> [AI →](https://docs.hanzo.ai/docs/openapi/ai) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                        |
| ------------- | -------------------------------------- |
| **Address**   | `https://api.hanzo.ai/v1/embeddings`   |
| **Method**    | `POST`                                 |
| **Operation** | `post_embeddings`                      |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY` |

Implements POST /v1/embeddings (OpenAI-compatible).

Body: {"model": "...", "input": "..."|\["...", ...], "encoding\_format"?, "dimensions"?}
It authenticates the caller, resolves the model to its upstream provider via
the shared routing table, rewrites the user-facing model name to the upstream
id, and proxies the request to the provider's /embeddings endpoint verbatim.

## Request

5 fields, body `application/json` (required).

| Field             | In   | Type    | Required | Description |
| ----------------- | ---- | ------- | -------- | ----------- |
| `dimensions`      | body | integer | —        |             |
| `encoding_format` | body | string  | —        |             |
| `input`           | body | any     | —        |             |
| `model`           | body | string  | —        |             |
| `user`            | body | string  | —        |             |

## Response

| Status | Body                     | Meaning                                             |
| ------ | ------------------------ | --------------------------------------------------- |
| `200`  | openai.EmbeddingResponse | Success.                                            |
| `401`  | —                        | No credential, or one this service does not accept. |
| `403`  | —                        | A valid credential that may not do this.            |

`200` body — 16 fields.

| Field                                              | In   | Type                           | Always | Description |
| -------------------------------------------------- | ---- | ------------------------------ | ------ | ----------- |
| `data`                                             | body | openai.Embedding\[]            | —      |             |
| `data[].embedding`                                 | body | number\[]                      | —      |             |
| `data[].index`                                     | body | integer                        | —      |             |
| `data[].object`                                    | body | string                         | —      |             |
| `model`                                            | body | string                         | —      |             |
| `object`                                           | body | string                         | —      |             |
| `usage`                                            | body | openai.Usage                   | —      |             |
| `usage.completion_tokens`                          | body | integer                        | —      |             |
| `usage.completion_tokens_details`                  | body | openai.CompletionTokensDetails | —      |             |
| `usage.completion_tokens_details.audio_tokens`     | body | integer                        | —      |             |
| `usage.completion_tokens_details.reasoning_tokens` | body | integer                        | —      |             |
| `usage.prompt_tokens`                              | body | integer                        | —      |             |
| `usage.prompt_tokens_details`                      | body | openai.PromptTokensDetails     | —      |             |
| `usage.prompt_tokens_details.audio_tokens`         | body | integer                        | —      |             |
| `usage.prompt_tokens_details.cached_tokens`        | body | integer                        | —      |             |
| `usage.total_tokens`                               | body | integer                        | —      |             |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo embeddings create
```

**SDK**

**.ts**

```ts
import { Configuration, AiApi } from 'hanzoai';

const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postEmbeddings({ dimensions: 0, encoding_format: "<encoding_format>" });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).post_embeddings(dimensions=0, encoding_format="<encoding_format>")
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AiAPI.PostEmbeddings(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, ai_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = ai_api::post_embeddings(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AiApi(client).postEmbeddings();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/embeddings \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "dimensions": 0,
       "encoding_format": "<encoding_format>"
     }'
```

**MCP**

MCP declares no tool for **ai** — `tools/list` on `https://api.hanzo.ai/v1/mcp` names the products it does reach. Use HTTP or an SDK.

---

[AI API](https://docs.hanzo.ai/docs/openapi/ai) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)