Request conventions

The wire format differs between protocols, but production clients can follow a common set of practices.

Content type

JSON APIs typically use:

Content-Type: application/json

File or media uploads may require multipart/form-data or another endpoint-specific format.

Model field

Do not assume a model ID is permanent.

{
  "model": "YOUR_MODEL_ID"
}

Read model IDs from configuration and validate them against current platform availability.

Credentials

Prefer headers rather than URLs.

OpenAI-compatible:

Authorization: Bearer YOUR_API_KEY

Anthropic:

x-api-key: YOUR_API_KEY

Gemini:

x-goog-api-key: YOUR_API_KEY

Streaming

Streaming clients need to handle long-lived connections, chunks, interruption, cancellation, time-to-first-byte, and overall timeout.

If the connection fails after partial output, do not automatically assume the request was never processed.

Request size

The service includes request-body protection. Images, audio, Base64 data, long conversation history, and tool schemas can grow request size quickly.

Reduce duplicate context and split very large workloads when appropriate.

Duplicate POST requests

Many generation endpoints are billable POST operations. A network timeout can happen after the server has already accepted a request.

Applications can use their own request IDs, task records, or state machines to prevent accidental duplicate execution.

Encoding and time

Use UTF-8 JSON. For time fields, follow the specific protocol definition. During troubleshooting, prefer explicit time ranges rather than assumptions based on local timezone.

Optional compatibility fields

A field existing in a protocol does not guarantee that every model supports it.

Start with a minimal request, add one advanced feature at a time, and return to the minimal payload when debugging.