Completions API¶

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

Quick Start: Available Endpoint¶

Feature Compatibility¶

Prompt Input Types¶

stdapi 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 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 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 behaviour 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 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:

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 https://api.example.com/v1/completions \
  -H "Authorization: Bearer $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"]
  }'

Examples¶

Single Prompt Completion¶

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 Prompt Completion¶

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

Streaming Completion¶

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": "Tell me a joke",
    "max_tokens": 50,
    "stream": true
  }'