Embeddings API¶

Generate vector embeddings for semantic search and RAG applications with Amazon Bedrock embedding models through an OpenAI-compatible interface.

Why Choose the Embeddings API?¶

Available Endpoints¶

Feature Compatibility¶

Model Support¶

Any Amazon Bedrock model that produces embeddings answers on this route — the Amazon Titan Embed and Amazon Nova embedding families, Cohere Embed, and TwelveLabs Marengo. A model that produces something else is refused with 400, naming it.

To list the models this deployment serves on this route, call search_models with route=openai_embedding. Which of them accept images, video or audio rather than text alone is covered under Multimodal Embeddings.

Model Name Aliases¶

Cohere models carry the dotted version their own API publishes, so the name you already send resolves without change:

• embed-v4.0 → cohere.embed-v4:0
• embed-english-v3.0 → cohere.embed-english-v3

Advanced Features¶

Embedding a Corpus in Bulk¶

A large corpus does not have to be embedded on the request path. Upload the requests as a file and run them through the Batch API against /v1/embeddings: they run without a connection held open, at the published batch rate, and the vectors are read back from the result file. One batched request embeds one input, and its vectors come back as numbers.

Provider-Specific Parameters¶

Access advanced embedding capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to Amazon Bedrock and allow you to access features unique to each embedding model provider.

Documentation: Bedrock Embedding Model Parameters

How It Works:

Add provider-specific fields at the top level of your request body alongside standard OpenAI parameters. The API automatically forwards these to the appropriate model provider via Amazon Bedrock.

Examples:

Cohere Embed v4 - Input Type:

{
  "model": "cohere.embed-v4:0",
  "input": "Semantic search transforms how we find information",
  "input_type": "search_query"
}

Amazon Titan Embed v2 - Normalization:

{
  "model": "amazon.titan-embed-text-v2:0",
  "input": "Product description for similarity matching",
  "normalize": true
}

Configuration Options:

Option 1: Per-Request

Add provider-specific parameters directly in your request body (as shown in examples above).

Option 2: Server-Wide Defaults

Configure default parameters for specific models via the DEFAULT_MODEL_PARAMS environment variable:

export DEFAULT_MODEL_PARAMS='{
  "cohere.embed-v4:0": {
    "input_type": "search_document",
    "truncate": "END"
  }
}'

Note: Per-request parameters override server-wide defaults.

Behavior:

• Compatible parameters: Forwarded to the model and applied
• Unsupported parameters: Return HTTP 400 with an error message

Multimodal Embeddings¶

Go beyond text! Supported models can process images, videos, and audio through base64 data URI input. This enables powerful cross-modal search and similarity features.

Input Format¶

Multimodal content is passed as base64-encoded data URIs:

data:<mime-type>;base64,<base64-encoded-content>

Example: Image Embedding¶

# First, encode your image to base64
IMAGE_B64=$(base64 -w 0 image.jpg)

# Send the embedding request
curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"amazon.nova-2-multimodal-embeddings-v1:0\",
    \"input\": \"data:image/jpeg;base64,$IMAGE_B64\"
  }"

Example: Video Embedding¶

Option 1: Base64-encoded video (for small files)

# First, encode your video to base64
VIDEO_B64=$(base64 -w 0 video.mp4)

# Send the embedding request
curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"amazon.nova-2-multimodal-embeddings-v1:0\",
    \"input\": \"data:video/mp4;base64,$VIDEO_B64\"
  }"

Option 2: S3 URL (for large files)

# Send the embedding request with S3 URL
curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-multimodal-embeddings-v1:0",
    "input": "s3://my-bucket/path/to/video.mp4"
  }'

Option 3: Files API reference (file-id:)

Reference a file previously uploaded via the Files API using the project-local file-id: URI scheme:

curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-multimodal-embeddings-v1:0",
    "input": "file-id:file-0190c51c7de7455d9b8c2efe27dfbf67"
  }'

Example: PDF Document Embedding¶

For PDFs, convert each page to an image and send via inputs along with page metadata (e.g., file_name, entities) in adjacent text parts. For RAG applications, smaller chunks often improve retrieval accuracy and reduce costs.

Cohere Embed v4 (supports multiple text+image pairs in one request):

# Convert PDF pages to images (using ImageMagick or similar tool)
convert -density 150 document.pdf page-%d.jpg

# Encode each page image to base64
PAGE_1=$(base64 -w 0 page-0.jpg)
PAGE_2=$(base64 -w 0 page-1.jpg)

# Generate document embedding with metadata
curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"cohere.embed-v4:0\",
    \"input\": [
      \"file_name: report.pdf, page: 1\",
      \"data:image/jpeg;base64,$PAGE_1\",
      \"file_name: report.pdf, page: 2\",
      \"data:image/jpeg;base64,$PAGE_2\"
    ]
  }"

TwelveLabs Marengo v3 (requires exactly one text + one image per request):

# Encode image to base64
IMAGE_B64=$(base64 -w 0 page-0.jpg)

# Generate text+image embedding (automatically uses text_image mode)
curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"twelvelabs.marengo-embed-3-0-v1:0\",
    \"input\": [
      \"A diagram showing the quarterly sales report\",
      \"data:image/jpeg;base64,$IMAGE_B64\"
    ]
  }"

Mixed-Content Batching¶

Combine text and multimodal inputs in a single request:

curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"cohere.embed-v4:0\",
    \"input\": [
      \"A beautiful sunset over mountains\",
      \"data:image/jpeg;base64,/9j/4AAQSkZJRg...\",
      \"Nature photography collection\"
    ]
  }"

Use Cases¶

• Visual Search: Find images similar to a query image or text description
• Video Analysis: Search and retrieve video content based on visual similarity or text descriptions
• Audio Similarity: Find similar audio clips or match audio to text descriptions
• Document Retrieval: Find relevant PDFs based on visual and textual content
• Cross-Modal Recommendations: Recommend images, videos, or audio based on text queries and vice versa
• Content Moderation: Analyze and classify multimodal content at scale

Build smarter search and recommendations! Explore available embedding models in the Models API.

Available Request Headers¶

This endpoint supports standard Bedrock headers for enhanced control over your requests. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

Performance Optimization¶

Example with headers:

curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-Service-Tier: flex" \
  -H "X-Amzn-Bedrock-PerformanceConfig-Latency: standard" \
  -d '{
    "model": "amazon.nova-2-multimodal-embeddings-v1:0",
    "input": ["Batch text 1", "Batch text 2", "Batch text 3"]
  }'

Try It Now¶

Single text embedding:

curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-multimodal-embeddings-v1:0",
    "input": "Semantic search transforms how we find information"
  }'

Batch processing with base64 encoding:

curl -X POST "$BASE/v1/embeddings" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-2-multimodal-embeddings-v1:0",
    "input": ["Product description", "User query", "Related content"],
    "encoding_format": "base64"
  }'