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.

At a glance¶

• The smallest schema of the text routes. Prompt in, text out, over the Amazon Bedrock Converse API — the smallest token footprint for MCP-based text agents and high-volume prompt-to-text workloads.
• Batch prompts. An array of prompts returns one choices[] entry per prompt, streaming included, with choices[].index identifying the prompt.
• File prompts. https://, s3://, data: and file-id: references bring images, documents, audio and video into a completion request.
• Every Chat Completions model answers here too, with the same service tiers and multi-region model access.
• Differs from OpenAI: OpenAI labels /v1/completions legacy and steers new projects to Chat Completions or Responses; here it is a first-class route with the same quality guarantees as the others.
• Differs by backend: models served by Bedrock Mantle — the OpenAI GPT-5.6 and GPT-6 families by default — take a single text prompt only; see Limits and behaviour to know.

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
  }'

Endpoints¶

Feature compatibility¶

Models¶

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.

Working with prompt inputs¶

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), served by the classic Converse endpoint — a Mantle-served model rejects any file prompt with 400.
• 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}
  }'

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"]
  }'

Limits and behaviour to know¶

A Mantle-served model takes one text prompt. The request is converted to a chat payload before it leaves the gateway, and that conversion accepts a single string: a batch of prompts, a file prompt of any scheme (https://, s3://, data:, file-id:), logprobs and suffix are each rejected with 400 naming what was refused. echo is honored, exactly as on the Bedrock Converse path below. The OpenAI GPT-5.6 and GPT-6 families are served from Mantle by default; clearing AWS_BEDROCK_MANTLE_PREFERRED_MODELS moves them to the classic endpoint, where the full prompt surface applies.

echo prepends the prompt, computed locally. Neither backend has an equivalent parameter; the gateway derives each choice's prompt from the text it already built the upstream request from and prepends it to that choice's completion (one leading chunk per choice, sent before any generated content, when streamed). On the Bedrock Converse path a file-only prompt has no text block to echo, so it echoes nothing, and a text + files collapse request echoes just its text instruction; a Mantle-served model only ever takes one text prompt, so every one of its n choices carries that same prompt.

Seven parameters are accepted and ignored on every model. best_of, frequency_penalty, presence_penalty, logit_bias, logprobs, seed and suffix are accepted, so a client that always sends them keeps working; the Amazon Bedrock Converse API has no equivalent for them and the completion is the same without them. stop, n and echo are honored.

A token-array prompt is rejected with 400. Token IDs are specific to the tokenizer that produced them, so send the text and let the serving model tokenize it.

At most 128 completions per request. A prompt array is served by one backend call per prompt, so the work a single request asks for is the number of prompts times n. That product is capped at 128 — the ceiling n alone already carries — and a request above it is rejected with 400 naming both parameters, before any backend call is made. 64 prompts with n=2 is served; 129 prompts is not.

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¶

Try it¶

Send a first completion in one line — then explore the richer input modes in Working with prompt inputs 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": "Write a limerick about the sea",
    "max_tokens": 60
  }'

Next steps¶

Next: Chat Completions API · Responses API · Files API · Models API