Media, Files, Batches, and asynchronous APIs

This page covers interfaces beyond ordinary Chat, Responses, Messages, and Embeddings. An experimental endpoint label describes contract maturity; it does not guarantee that the current build has a creatable Provider Profile.

Check before calling

1. In Providers, confirm the required Profile is not withheld and the connection test passes.
2. In Deployments, confirm real model, capability evidence, Price Version, and concurrency.
3. In Routes, create a public alias. Resource Routes must resolve uniquely to one eligible Deployment.
4. In Projects, authorize the alias and configure budgets, limits, and policy.
5. Call with the Project Gateway Key and save every opaque ID returned by resource creation.

The current build has no Bedrock Runtime/Agent Runtime Profile, so /v1/rerank and /v1/async/invocations have no creatable backend. Their contracts remain for compatibility development, not as an availability claim.

Content safety and media

Moderations, Images, Speech, and Transcriptions use a normal Gateway Key and resolve the Route from model:

curl https://halro.example.com/v1/moderations -H "Authorization: Bearer $HALRO_GATEWAY_KEY" -H "Content-Type: application/json" -d '{"model":"moderation","input":"content to inspect"}'
curl https://halro.example.com/v1/images/generations -H "Authorization: Bearer $HALRO_GATEWAY_KEY" -H "Content-Type: application/json" -d '{"model":"image","prompt":"a paper-craft cat","n":1,"size":"1024x1024"}'
curl https://halro.example.com/v1/audio/speech -H "Authorization: Bearer $HALRO_GATEWAY_KEY" -H "Content-Type: application/json" -d '{"model":"speech","input":"Hello","voice":"alloy"}' --output speech.bin
curl https://halro.example.com/v1/audio/transcriptions -H "Authorization: Bearer $HALRO_GATEWAY_KEY" -F model=transcription -F file=@sample.wav

Validate media quality, safety, and real Provider availability separately; protocol fixtures prove only request/response shape.

Currently accepted media fields

JSON endpoints use strict decoding; unknown fields are rejected.

Currently accepted media fields

Endpoint	Required	Optional and range
Moderations	input as valid non-null JSON	model; default omni-moderation-latest
Images	non-empty prompt	model, quality, response_format, size, style; n defaults to 1, range 1–10
Speech	model, non-empty input, voice	response_format; speed range 0.25–4
Transcriptions	exactly one multipart file and non-empty model	language, prompt, response_format; temperature range 0–1

Unknown multipart fields, duplicate Files, and Files without filenames return 400.

Files and Batches

File multipart bodies have no model, so specify the resource Route with Halro-Route and use a stable Idempotency-Key:

FILE_RESPONSE=$(curl -fsS https://halro.example.com/v1/files \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Halro-Route: batch-files" \
  -H "Idempotency-Key: order-20260905-file-v1" \
  -F purpose=batch -F file=@input.jsonl)

Save id, then create a Batch. It inherits the File’s Provider, Deployment, Profile, and Region and does not reroute:

curl https://halro.example.com/v1/batches \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260905-batch-v1" \
  -d '{"input_file_id":"file_...","endpoint":"/v1/chat/completions","completion_window":"24h"}'

Poll GET /v1/batches/{id} at a bounded rate, then read output_file_id or error_file_id with GET /v1/files/{id}/content. Do not delete an input File before dependent resources are preserved.

Files and Batches fields

Files and Batches fields

Operation	Required header or field	Optional and range
Create File	Authorization, Halro-Route, stable Idempotency-Key; multipart file, purpose	No other multipart fields; exactly one named File
Create Batch	input_file_id, endpoint, completion_window="24h"; stable Idempotency-Key	metadata at most 16 items; key 1–64, value at most 512 chars
Retrieve/cancel Batch	opaque Batch ID in path	No body; status comes from the creation-bound target
Retrieve/download/delete File	opaque File ID in path	No body; visible only to the creating Project

Files and Batches fields

Bound Profile	Accepted Batch endpoint	completion_window
openai.media-resources.v1	/v1/chat/completions, /v1/responses, /v1/embeddings	24h only
anthropic.messages.2023-06-01	/v1/chat/completions only	24h only

Rerank and asynchronous generation

These contracts are retained, but the current build has no creatable Provider Profile:

Rerank and asynchronous generation

Endpoint	Required	Optional and range
Rerank	model:string, non-empty query:string up to 10,000 bytes, documents:string[] with 1–1,000 non-empty items up to 50,000 bytes each	top_n:int, default document count, range 1–document count
Async create	model:string, non-empty prompt:string up to 512 bytes, s3_output_uri:string	duration_seconds:int, dimension:string, fps:string, seed:int64; gateway declares no further enum/range
Async get/cancel	opaque Invocation ID in path	No body; cancellation fails closed without upstream confirmation

All JSON requests reject unknown fields. Async s3_output_uri must use s3://, contain a bucket, end its path in /, and contain no userinfo, query, or fragment.

Resource boundaries and retries

• File retention is at most 30 days; Batch and Async records at most 7 days.
• IDs are visible only to the creating Project.
• Retrieval, cancellation, and deletion return to the target bound at creation and never fallback.
• For 429, honor Retry-After. If an ID exists, query it first. If create returned no ID, retry the identical attribution/body with the same Idempotency-Key and bounded backoff. On persistent 409, keep the original key, stop creating, and escalate.
• Deletion never reverses Provider cost already incurred.

See Retries, timeouts, and idempotency and Experimental endpoints.