embeddings

---
name: embeddings
description: Use when the user needs OpenAI-compatible or Gemini embeddings through CursorAI for retrieval, clustering, indexing, reranking preparation, or vector database ingestion.
license: MIT
---

# Embedding Models on CursorAI

## Overview
This Skill teaches an agent how to use OpenAI and Gemini Embeddings via CursorAI through CursorAI's unified API gateway.
Base URL is `https://api.cursorai.art`. Authentication is always `Authorization: Bearer $CURSORAI_API_KEY` from the `CURSORAI_API_KEY` environment variable.

### Supported Models
- `text-embedding-3-small`
- `text-embedding-3-large`
- `gemini-embedding-001`

### Core Features
- dense vectors
- batch embedding
- OpenAI format
- Gemini format
- retrieval indexing

## When to Use
- Use this Skill when the user asks for implementation details, request payloads, scripts, or troubleshooting for this CursorAI capability.
- Use it when one of the supported models or endpoints below is explicitly requested.
- Use it when parameter choice affects output quality, cost, latency, media format, or async polling behavior.
- Do not make live calls if `CURSORAI_API_KEY` is missing; run dry-run examples instead.
- Do not submit costly media jobs or duplicate async tasks until the user confirms the exact prompt and parameters.

## Authentication Configuration
- Required environment variable: `CURSORAI_API_KEY`.
- Base URL: `https://api.cursorai.art`.
- Auth scheme: Bearer token in the `Authorization` header.
- JSON requests use `Content-Type: application/json`.
- Multipart endpoints must let the HTTP client set the multipart boundary.
- Never log or write the API key to generated artifacts.

## API Endpoint Quick Reference
| Method | Path | Parameters | Response format | Sync/Async | Risk |
|---|---|---|---|---|---|
| `POST` | `/v1/embeddings` | `model`, `input`; optional `dimensions`, `encoding_format` | OpenAI embedding object with `data[].embedding`, `usage` | sync | moderate |
| `POST` | `/v1beta/models/{model}:embedContent` | Path `model`; body `content.parts[].text`; optional task type | Gemini embedding object with `embedding.values[]` | sync | moderate |

## Typical Workflow
1. Normalize and chunk source text.
2. Choose OpenAI or Gemini embedding format.
3. Batch inputs within provider limits.
4. Store vectors with source ids and metadata.
5. Validate vector dimensions before adding to an existing index.

## Request And Response Examples
### POST /v1/embeddings
Request:
```json
{
  "model": "text-embedding-3-small",
  "input": [
    "API docs become searchable vectors."
  ]
}
```
Success response shape:
```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0123,
        -0.0456,
        0.0789
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 6,
    "total_tokens": 6
  }
}
```
Parse: treat HTTP 2xx as success, then extract the endpoint-specific final field such as `choices`, `content.parts`, `data`, `text`, `id`, `status`, `imageUrl`, `audio_url`, or `video_url`.

### POST /v1beta/models/{model}:embedContent
Request:
```json
{
  "content": {
    "parts": [
      {
        "text": "API docs become searchable vectors."
      }
    ]
  }
}
```
Success response shape:
```json
{
  "embedding": {
    "values": [
      0.0123,
      -0.0456,
      0.0789
    ]
  }
}
```
Parse: treat HTTP 2xx as success, then extract the endpoint-specific final field such as `choices`, `content.parts`, `data`, `text`, `id`, `status`, `imageUrl`, `audio_url`, or `video_url`.


## Parameter Selection Guide
| Goal | Choose | Guidance |
|---|---|---|
| Default retrieval | `text-embedding-3-small` | Use for cost-efficient semantic search. |
| Higher recall | `text-embedding-3-large` | Use when quality matters and index dimension can change. |
| Gemini stack | `gemini-embedding-001` | Use when the rest of the pipeline uses Gemini-native data. |
| Existing index | `dimensions` only if supported | Never change vector dimensions for an existing collection. |

## Error Handling
| Code or signal | Meaning | Recovery |
|---|---|---|
| `400/422` | Invalid JSON, missing required field, unsupported model, bad media field. | Compare the request with the endpoint table, remove unsupported parameters, and retry once. |
| `401` | Missing or invalid bearer token from `CURSORAI_API_KEY`. | Export `CURSORAI_API_KEY` and verify the `Authorization: Bearer ...` header is sent. |
| `403` | The key is valid but lacks model or endpoint access. | Switch to an allowed model or request access before retrying. |
| `404` | Wrong path, model path parameter, or task id. | Check path templates and saved ids; do not invent task ids. |
| `409` | Duplicate or conflicting async action. | Poll the existing task before submitting a replacement job. |
| `413/415` | Payload too large or unsupported media type. | Compress media, use a supported MIME type, or switch to multipart where required. |
| `429` | Rate limit or quota pressure. | Back off exponentially and reduce concurrency; do not fan out retries. |
| `5xx/timeout` | CursorAI gateway or upstream provider failure. | Retry idempotent reads; for submit calls, check whether a task id was returned before resubmitting. |

## Verification Checklist
- Run `python3 scripts/healthcheck.py --dry-run` before live testing.
- Run `python3 scripts/example_call.py --dry-run` to inspect method, URL, headers, and payload.
- Use `python3 scripts/example_call.py --live` only after confirming the request is acceptable.
- Treat only HTTP 2xx as success; 4xx, 5xx, and network failures are script failures.
- Confirm the response contains the expected final field for `/v1/embeddings` before presenting the result.

## Operational Notes
- Keep chunking deterministic so document ids map back to source text.
- Do not mix vector dimensions in one index.
- Batch cautiously; a failed batch should be retryable without duplicating stored ids.

## Example Python Skeleton
```python
import os
import requests

base_url = "https://api.cursorai.art"
api_key = os.environ["CURSORAI_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
response = requests.post(base_url + "/v1/embeddings", headers=headers, json={'model': 'text-embedding-3-small', 'input': ['API docs become searchable vectors.']})
response.raise_for_status()
print(response.json())
```

## Maintenance Guidance
- Keep endpoint examples aligned with `API_REFERENCE.md` and CursorAI's published docs.
- Keep all examples on `https://api.cursorai.art` and `CURSORAI_API_KEY`.
- Re-run `python3 -m py_compile` after script edits.