# Embed API (v2)

**POST** `/v2/embed`

This endpoint returns text embeddings. An embedding is a list of floating point numbers that captures semantic information about the text that it represents.

Embeddings can be used to create text classifiers as well as empower semantic search. To learn more about embeddings, see the embedding page.

If you want to learn more how to use the embedding model, have a look at the [Semantic Search Guide](https://docs.cohere.com/docs/semantic-search).

Base URL: `https://api.cohere.com`

## Authorization

| Option | Scheme | Type | Sent as | Scopes |
| --- | --- | --- | --- | --- |
| Option 1 | `bearerAuth` | `http` | `Authorization: Bearer <token>` | — |

## Header parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Client-Name` | `string` | No | The name of the project that is making the request. |

## Request body

Optional. Media type: `application/json`

### Example request body

```json
{
  "embedding_types": [
    "float"
  ],
  "images": [
    "string"
  ],
  "input_type": "classification",
  "inputs": [
    {
      "content": [
        {
          "image_url": {
            "url": "string"
          },
          "type": "image_url"
        }
      ]
    }
  ],
  "max_tokens": 0,
  "model": "string",
  "output_dimension": 0,
  "priority": 0,
  "texts": [
    "string"
  ],
  "truncate": "END"
}
```

## Responses

| Status | Description | Media type |
| --- | --- | --- |
| `200` | OK | `application/json` |
| `400` | This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields | `application/json` |
| `401` | This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions | `application/json` |
| `403` | This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions | `application/json` |
| `404` | This error is returned when a resource is not found. This could be because: - The endpoint does not exist - The resource does not exist eg model id, dataset id | `application/json` |
| `422` | This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields | `application/json` |
| `429` | Too many requests | `application/json` |
| `498` | This error is returned when a request or response contains a deny-listed token. | `application/json` |
| `499` | This error is returned when a request is cancelled by the user. | `application/json` |
| `500` | This error is returned when an uncategorised internal server error occurs. | `application/json` |
| `501` | This error is returned when the requested feature is not implemented. | `application/json` |
| `503` | This error is returned when the service is unavailable. This could be due to: - Too many users trying to access the service at the same time | `application/json` |
| `504` | This error is returned when a request to the server times out. This could be due to: - An internal services taking too long to respond | `application/json` |

### Example response: 200 — OK

```json
{
  "embeddings": {
    "base64": [
      "string"
    ],
    "binary": [
      [
        0
      ]
    ],
    "float": [
      [
        0
      ]
    ],
    "int8": [
      [
        0
      ]
    ],
    "ubinary": [
      [
        0
      ]
    ],
    "uint8": [
      [
        0
      ]
    ]
  },
  "id": "string",
  "images": [
    {
      "bit_depth": 0,
      "format": "string",
      "height": 0,
      "width": 0
    }
  ],
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "response_type": "embeddings_by_type",
  "texts": [
    "string"
  ]
}
```

### Example response: 400 — This error is returned when the request is not well formed. This could be because:
  - JSON is invalid
  - The request is missing required fields
  - The request contains an invalid combination of fields

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 401 — This error indicates that the operation attempted to be performed is not allowed. This could be because:
  - The api token is invalid
  - The user does not have the necessary permissions

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 403 — This error indicates that the operation attempted to be performed is not allowed. This could be because:
  - The api token is invalid
  - The user does not have the necessary permissions

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 404 — This error is returned when a resource is not found. This could be because:
  - The endpoint does not exist
  - The resource does not exist eg model id, dataset id

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 422 — This error is returned when the request is not well formed. This could be because:
  - JSON is invalid
  - The request is missing required fields
  - The request contains an invalid combination of fields

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 429 — Too many requests

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 498 — This error is returned when a request or response contains a deny-listed token.

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 499 — This error is returned when a request is cancelled by the user.

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 500 — This error is returned when an uncategorised internal server error occurs.

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 501 — This error is returned when the requested feature is not implemented.

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 503 — This error is returned when the service is unavailable. This could be due to:
  - Too many users trying to access the service at the same time

```json
{
  "id": "string",
  "message": "string"
}
```

### Example response: 504 — This error is returned when a request to the server times out. This could be due to:
  - An internal services taking too long to respond

```json
{
  "id": "string",
  "message": "string"
}
```

## Related pages

- [/audio/transcriptions](./tags/audio-transcriptions.md)
- [/batches](./tags/batches.md)
- [/connectors](./tags/connectors.md)
- [/datasets](./tags/datasets.md)
- [/embed-jobs](./tags/embed-jobs.md)
- [/finetuning](./tags/finetuning.md)
- [/models](./tags/models.md)
- [API Reference](../../api.md)
- [Authorize with oAuth](./oauthauthorize-connector.md)
- [Cancel a batch](./cancelbatch.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.