Request reasoning and media safely
Check reasoning support and send media in the correct protocol shape without assuming model support.
Reasoning and media support depends on the canonical model, protocol, plan and available execution. Read GET /v1/models first and select an available ID; do not infer support from a display name. The catalog's capabilities.reasoning field helps check reasoning, but it does not currently publish separate image, audio or document capability flags. The table below shows accepted request shapes by protocol, not a guarantee that every model accepts every media type. Add one new feature at a time so that a rejected field is easy to identify.
Request reasoning
| Protocol | Request field | What to check |
|---|---|---|
| Responses | reasoning.effort | Choose an effort supported by the model. reasoning.summary asks for a summary, not the full internal reasoning. |
| Chat Completions | reasoning_effort | Use one effort value; a sentence in a message is not a substitute for this field. |
| Messages | thinking or output_config.effort | Use native Messages syntax. thinking.type: enabled needs a positive budget_tokens; adaptive needs output_config.effort. |
For a model with capabilities.reasoning: true, a minimal Responses body is:
json
{
"model": "gpt-6-sol",
"input": "Compare two backup approaches and explain your choice.",
"reasoning": { "effort": "low" },
"max_output_tokens": 256
}
gpt-6-sol is a concrete catalog ID; choose an ID available to your key if it is not listed. The service preserves protocol-native reasoning when the model supports it. An unsupported combination returns unsupported_capability before a paid generation attempt. Do not treat a missing reasoning block as an error when the model or mode returns only the final text.
Send media in the correct shape
Check the syntax for your chosen protocol, then send only the input type your application needs. Because the public catalog has no media flags, a free model-list request cannot yet verify a particular model and media-type combination. If no available execution supports the requested combination, the API returns unsupported_capability before paid work; do not turn that rejection into an automatic sweep of paid model calls.
| Input | Responses | Chat Completions | Messages |
|---|---|---|---|
| Image | input_image block with one image_url or file_id | image_url block with an object containing { url, detail? } | image block with a base64 or url source |
| Audio | input_audio block with input_audio.data and wav or mp3 format | input_audio block with the same fields | Check the catalog and client format; do not copy an OpenAI block into Messages unchanged |
| Document | input_file block with one file_data, file_id, or file_url | Use another supported protocol for files | document block with a PDF (base64 or url) or text source |
Image and document URLs must use HTTPS without embedded usernames, passwords, or private hosts. For sensitive content, prefer a supported binary input so that a secret URL does not enter client logs. Use file_id only for a file that exists in the compatible client workflow; the model catalog does not upload files.
Keep the full JSON body below 4 MiB, including base64 expansion; an oversized body returns request_too_large, and the ingress may reject a body above 5 MiB before JSON handling. If invalid_request names a malformed block, correct that shape. For unsupported_capability, check the model and protocol before deliberately changing the request; repeating it unchanged cannot add support. A free model-by-media capability matrix is not published yet, so do not infer media support from the model name or the catalog's general flags.