Completions API¶

Generate text completions with Amazon Bedrock foundation models—including Claude, Nova, Llama, and more—through an OpenAI-compatible interface using the simple completions format.

Why Choose the Completions API?¶

Available Endpoints¶

Feature Compatibility¶

Model Support¶

Every model the Chat Completions API serves also answers here — the same model classes back both routes, with the prompt adapted into a single Converse turn. That means all models supported by the Amazon Bedrock Converse and Converse Stream API, plus every model served by Bedrock Mantle when enabled. The Mantle conversion behavior tabled above is the same three serving paths described on the Chat Completions page.

To list the models this deployment serves on this route, call search_models with route=openai_completion.

Model Name Aliases¶

The dynamic aliases published by the official provider APIs resolve here too, exactly as they do for chat — gpt-oss-20b reaches openai.gpt-oss-20b-1:0.

Prompt Input Types¶

stdapi.ai extends the standard completions interface with multiple input modes:

String Prompt (Standard)¶

The simplest input — a single text prompt:

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": "The capital of France is",
    "max_tokens": 20
  }'

Batch Prompts¶

Send multiple independent prompts in a single request — the server returns one choices[] entry per prompt:

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": ["One plus one is", "Two plus two is", "Three plus three is"],
    "max_tokens": 10
  }'

Text + Files: Single-Request Multimodal Collapse¶

When the prompt list contains exactly one text string and one or more file references, stdapi.ai packs them in input order into a single multimodal request and returns one choice. The text becomes a text block and each file becomes an image / document / audio / video Bedrock block (content type auto-detected) — the natural "ask once using these files as context" pattern.

• Trigger: list with exactly one str element and ≥1 URL elements (https://, s3://, data:, file-id:).
• Effect: elements are resolved concurrently, packed as Bedrock content blocks preserving input order, and sent as a single request. You get one Completion choice back.
• Requires: a model that supports the target modalities (e.g. Claude, Nova for image / document input).
• Unchanged otherwise: any other shape returns one Completion choice per list element. Each str becomes a text block; each InputFileUrl becomes the content block matching its detected MIME type (image, video, audio, document). See Files-only prompts below.

Image analysis with a base64 data URI (Claude handles image input):

IMAGE_B64=$(base64 < chart.png | tr -d '\n')

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
  "prompt": [
    "Describe what is shown in this chart in one short sentence:",
    "data:image/png;base64,${IMAGE_B64}"
  ],
  "max_tokens": 80
}
JSON

Or, referencing previously uploaded files via file-id::

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "prompt": [
      "Summarize the main findings and cross-reference with the appendix:",
      "file-id:file-abc123",
      "file-id:file-def456"
    ],
    "max_tokens": 400
  }'

Input order is preserved — place the instruction before, after, or between the files as best fits your use case.

Files-Only Prompts¶

When the prompt is a lone file — or a list of files without any text string — stdapi.ai forwards each file to the model using its detected modality (image, video, audio, document). No instruction is injected:

• prompt: "<file-id or URL>" → one request, one choice, with a single media block.
• prompt: [<file1>, <file2>, …] → one request per file (batch), one choice per file, each carrying its own media block.

The request reaches the model as-is; the model returns output or an error depending on whether it supports that modality (for example, Claude handles images and documents, Nova handles images, video, and documents). Use this shape for quick "what is this?" queries where the model's default behavior is enough; for tighter control over the response, prefer the collapse pattern above with an explicit instruction.

IMAGE_B64=$(base64 < screenshot.png | tr -d '\n')

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
  "prompt": "data:image/png;base64,${IMAGE_B64}",
  "max_tokens": 120
}
JSON

URL, S3, and Files API Inputs (Extension)¶

stdapi.ai supports additional input schemes beyond the OpenAI standard:

• https:// — Load prompt from an HTTP URL
• s3://bucket/key/file.txt — Load directly from S3
• data:text/plain;base64,... — Embedded base64 data
• file-id:file-abc123 — Reference files uploaded via the Files API

Using file-id: for Prompt Input¶

Reference files uploaded via the Files API using the file-id: URI scheme. Useful for long prompts or when reusing the same prompt across multiple requests:

# Upload a text file
FILE_ID=$(curl -s -X POST "$BASE/v1/files" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "purpose=assistants" \
  -F "file=@prompt.txt" | jq -r .id)

# Reference it in a completion request
curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"amazon.nova-micro-v1:0\",
    \"prompt\": \"file-id:${FILE_ID}\",
    \"max_tokens\": 100
  }"

Using S3 for Prompt Input¶

Reference files directly in S3 without uploading to stdapi.ai:

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": "s3://my-bucket/prompts/essay-topic.txt",
    "max_tokens": 500
  }'

The gateway reads the file from S3 using your configured IAM role — no pre-signed URLs required.

Streaming¶

Set "stream": true to receive incremental text deltas as Server-Sent Events terminated by data: [DONE]:

curl -N -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": "Write a short story",
    "max_tokens": 100,
    "stream": true
  }'

Usage in Streaming Responses¶

Request usage statistics on the final chunk by setting stream_options.include_usage:

curl -N -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": "Hello",
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Available Request Headers¶

This endpoint supports standard Bedrock headers for enhanced control over your requests — they are applied by the shared request middleware, exactly as on the Chat Completions API. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

Performance Optimization¶

Model-Specific Features¶

TwelveLabs Pegasus¶

twelvelabs.pegasus-1-2-v1:0 is a video-understanding model. The Completions endpoint supports multimodal input: pass an array with exactly one text instruction and one video URL as prompt — the server combines them into a single Pegasus request.

• temperature and max_tokens are forwarded.
• A text-only prompt without a video returns HTTP 400 (Pegasus requires exactly one video).

Video input formats: s3://bucket/key, https://…, data:video/mp4;base64,…, or file-id:…. Videos above 18.75 MB are automatically uploaded to S3.

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "twelvelabs.pegasus-1-2-v1:0",
    "prompt": ["Describe what happens in this video.", "s3://my-bucket/video.mp4"]
  }'

Try It Now¶

Send your first completion in one line — then explore the richer input modes shown in Prompt Input Types above:

curl -X POST "$BASE/v1/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.nova-micro-v1:0",
    "prompt": "Say hello world",
    "max_tokens": 20
  }'

Ready to build with AI? Check out the Models API to see all available foundation models!