API Overview¶

stdapi.ai provides the OpenAI API interface backed by AWS Bedrock foundation models and AWS AI services. Use your existing OpenAI SDKs by simply changing the base URL.

Why this matters:

No code rewrites - Your existing OpenAI code works immediately
Access 80+ models - Claude, Nova, Llama, DeepSeek, Stable Diffusion, and more through one API
Multi-modal AI - Chat, images, audio, embeddings—all OpenAI-compatible
AWS-native features - Prompt caching, reasoning modes, guardrails accessible through standard API

Interactive Documentation¶

stdapi.ai provides multiple interfaces for exploring and testing the API—choose the one that fits your workflow:

📚 Documentation Resources¶

Complete API Reference – In-depth guides for every endpoint with parameter details
OpenAPI Specification – Full machine-readable schema for integration and tooling

🎮 Live API Playground¶

When running the server, access these interactive interfaces:

Interface	URL	Best For
Swagger UI	`http://localhost/docs`	Testing endpoints directly in your browser with live request/response examples
ReDoc	`http://localhost/redoc`	Reading and searching through clean, organized documentation
OpenAPI Schema	`http://localhost/openapi.json`	Generating client code or importing into API tools like Postman

OpenAI SDK-Compatible API¶

Access AWS-powered AI services through the OpenAI API interface. Use official OpenAI SDKs by simply changing the base URL—no custom clients needed.

What you can build:

Conversational AI - Chatbots, assistants, customer support with multi-modal understanding
Content generation - Images, articles, summaries, translations
Voice applications - Speech-to-text transcription, text-to-speech synthesis
Semantic search - RAG, document Q&A, knowledge bases with embeddings
Multi-modal apps - Process text, images, audio, video, and documents together

Supported Endpoints:

Category	Endpoint	Capability	Documentation
💬 Chat	`POST /v1/chat/completions`	Multi-modal conversations with text, images, video, documents	Chat Completions →
🎨 Images	`POST /v1/images/generations`	Text-to-image generation	Generations →
	`POST /v1/images/edits`	Image editing and transformations	Edits →
	`POST /v1/images/variations`	Generate image variations	Variations →
🔊 Audio	`POST /v1/audio/speech`	Text-to-speech synthesis	Text to Speech →
	`POST /v1/audio/transcriptions`	Speech-to-text transcription	Transcriptions →
	`POST /v1/audio/translations`	Speech-to-English translation	Translations →
🧠 Embeddings	`POST /v1/embeddings`	Vector embeddings for semantic search	Embeddings →
📋 Models	`GET /v1/models`	List available models	Models →

Backend Services:

AWS Bedrock - 80+ foundation models (Claude, Nova, Llama, DeepSeek, Stable Diffusion, etc.)
AWS Polly - Neural text-to-speech in 60+ languages
AWS Transcribe - Speech-to-text with speaker diarization
AWS Translate - Neural machine translation

Compatible SDKs: Official OpenAI SDKs (Python, Node.js, Go, Ruby, .NET, Java, etc.)

Quick Start Guide¶

This guide shows how to use stdapi.ai with OpenAI SDKs.

stdapi.ai works with official OpenAI client libraries—no custom clients needed:

Python

pip install openai

from openai import OpenAI

# Initialize client with your stdapi.ai endpoint
client = OpenAI(
    base_url="https://your-deployment-url/v1",
    api_key="your-api-key"
)

# Use AWS Bedrock models through the familiar OpenAI interface
response = client.chat.completions.create(
    model="amazon.nova-micro-v1:0",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ]
)

print(response.choices[0].message.content)

# Pass provider-specific parameter through `extra_body`:
response = client.chat.completions.create(
    model="anthropic.claude-sonnet-4-5-20250929-v1:0",
    messages=[{"role": "user", "content": "Solve this complex problem..."}],
    extra_body={
        "top_k": 0.5
    }
)

Node.js

npm install openai

import OpenAI from 'openai';

// Initialize client with your stdapi.ai endpoint
const client = new OpenAI({
  baseURL: 'https://your-deployment-url/v1',
  apiKey: 'your-api-key'
});

// Use AWS Bedrock models through the familiar OpenAI interface
const response = await client.chat.completions.create({
  model: 'amazon.nova-micro-v1:0',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing in simple terms.' }
  ]
});

console.log(response.choices[0].message.content);

cURL

curl -X POST "https://your-deployment-url/v1/chat/completions" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in simple terms."}
    ]
  }'

Understanding Compatibility¶

What "Compatible" Means¶

stdapi.ai implements the API from source specification with AWS services as the backend. This means:

✅ Same Request Format: Use identical request bodies and parameters
✅ Same Response Structure: Receive responses in the expected format
✅ Same SDKs: Use official client libraries
✅ Drop-in Replacement: Change only the base URL and model ID

Handling Parameter Differences¶

Different providers support different features. stdapi.ai handles this gracefully:

Silent Ignoring (Safe Parameters)¶

Parameters that don't affect output are accepted but ignored:

# This works—unsupported parameters are silently ignored
response = client.chat.completions.create(
    model="amazon.nova-micro-v1:0",
    messages=[{"role": "user", "content": "Hello"}],
    user="user-123",  # Logged but doesn't affect AWS processing
)

Clear Errors (Behavior-Changing Parameters)¶

Parameters that would change output return helpful errors:

# This returns HTTP 400 with a clear explanation
response = client.chat.completions.create(
    model="amazon.nova-micro-v1:0",
    messages=[{"role": "user", "content": "Hello"}],
    logit_bias={123: 100},  # Not supported—clear error returned
)

Understanding the Architecture¶

%%{init: {'flowchart': {'htmlLabels': true}} }%%
flowchart LR
  app["<img src='../styles/logo_openai.svg' style='height:64px;width:auto;vertical-align:middle;' /> Your App<br/>(OpenAI SDK)"] -->|HTTPS /v1/*| stdapi["<img src='../styles/logo.svg' style='height:64px;width:auto;vertical-align:middle;' /> stdapi.ai<br/>API Gateway"]
  stdapi --> bedrock["<img src='../styles/logo_amazon_bedrock.svg' style='height:64px;width:auto;vertical-align:middle;' /> AWS Bedrock"]
  stdapi --> polly["<img src='../styles/logo_amazon_polly.svg' style='height:64px;width:auto;vertical-align:middle;' /> AWS Polly"]
  stdapi --> transcribe["<img src='../styles/logo_amazon_transcribe.svg' style='height:64px;width:auto;vertical-align:middle;' /> AWS Transcribe"]
  stdapi --> s3["<img src='../styles/logo_amazon_s3.svg' style='height:64px;width:auto;vertical-align:middle;' /> AWS S3"]

Request Flow:

Your application uses the standard OpenAI SDK
Requests go to stdapi.ai's /v1/* endpoints instead of OpenAI
stdapi.ai translates OpenAI-format requests to AWS service APIs
AWS services process the requests
Responses are formatted as OpenAI-compatible responses
Your application receives familiar OpenAI response structures

Discovering Available Models¶

To see all models available in your deployment:

Using the API:

curl https://your-deployment-url/v1/models \
  -H "Authorization: Bearer your-api-key"

Using OpenAI SDK:

client = OpenAI(base_url="https://your-deployment-url/v1")
models = client.models.list()
for model in models:
    print(f"{model.id} - {model.owned_by}")

This returns all AWS Bedrock models available in your configured regions, including model IDs, providers, and capabilities.

See Models API documentation for details.

Next Steps¶

Start building:

Chat Completions API - Conversational AI with multi-modal support (text, images, video, documents)
Images API - Text-to-image generation, editing, and variations
- Generations - Create images from text
- Edits - Modify existing images
- Variations - Generate variations of images
Audio APIs - Text-to-speech, transcription, translation
- Speech - Text-to-speech synthesis
- Transcriptions - Speech-to-text
- Translations - Speech-to-English translation
Embeddings API - Vector embeddings for semantic search and RAG
Models API - List and discover available models

Configure your deployment:

Configuration Guide - Environment variables, AWS regions, security settings
Monitoring & Logging - Observability, debugging, CloudWatch integration

Explore integrations:

Use Cases - Open WebUI, n8n, Continue.dev, and more
Getting Started - Deploy to AWS with Terraform