openai/o3, served by Comfy Router from OpenAI.
Input: Text, Image · Output: Text
Quick start
Create a key in your Comfy workspace and export it asCOMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk and npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP.
Model ID: openai/o3
Endpoint: POST https://api.comfy.org/v2/models/openai/o3
- Wait for the result
- Queue and collect later
The same body, sent to
POST https://api.comfy.org/v2/models/openai/o3/requests. Router answers 201 with a request_id as soon as the run is admitted, and the result is collected once it is ready, from this process or another one. Queued delivery walks through status, cancellation and collection.Schema
Input
Text, image or file inputs to the model, used to generate a response. The one field of this contract Router cannot supply, and the only entry in
required below.An upper bound for the number of tokens generated for a response, including visible output tokens and reasoning tokens. On a reasoning id this ceiling is shared with the hidden reasoning tokens, so a small value can consume the whole budget before any visible text — which is why the reasoning smoke cases send 1024 where the chat ones send 16.Range:
1 to …OpenAI model identifier. On Comfy Router this field is OPTIONAL and Router fills it from the
{model} path segment; an explicit null is replaced the same way. Sending a value that disagrees with the path is refused.REASONING TIER ONLY. Configuration for reasoning models, e.g.
{"effort": "medium"}. Forwarded unchanged; see OpenAI’s reasoning guide for the accepted keys. A chat-tier id ignores it.Declared so a caller who sends it is not refused, but INERT on this surface: Router SETTLES it to
false before dispatch, because it captures the provider response rather than relaying a text/event-stream — which it cannot decode, so a streamed generation would be billed by OpenAI and metered by nobody. No Comfy surface serves the stream: the v1 POST /proxy/openai/v1/responses ingress refuses stream: true with a 400 and never forwards the request upstream, so omit the field or send false on either surface and read the completed response as one JSON body.Sampling temperature. CHAT TIER ONLY: the o-series reasoning ids (
o1, o1-pro, o3, o4-mini) reject this parameter at OpenAI. Router does not refuse it for them — see this component’s note on why the two tiers share one schema — so a reasoning call that sends it is answered by OpenAI’s own error.Range: 0 to 2Output-format configuration, e.g.
{"format": {"type": "json_schema", ...}} for Structured Outputs. Forwarded unchanged.How the model should select which tool to use. Either a string mode or an object naming a tool.
Tool definitions the model may call. Router does not narrow the tool taxonomy; see OpenAI’s Responses API reference for the accepted shapes.
Truncation strategy when the context exceeds the model’s window. The enum IS enforced here, unlike the three vocabularies above, because these two values are the complete set OpenAI documents and it has not grown. An explicit
null is still accepted, on the same terms as the fields above it.Possible values: auto, disabledToken-usage envelope. Present on this contract because the v1 operation declares it on the request body; OpenAI populates it on the RESPONSE, so a caller has no reason to send it.
GET /v2/models/openai/o3/openapi.json, the same document it validates a call against before the request reaches the provider.
Output
Inserts a system (or developer) message as the first item in the model’s context.When using along with
previous_response_id, the instructions from a previous
response will not be carried over to the next response. This makes it simple
to swap out system (or developer) messages in new responses.An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
The truncation strategy to use for the model response.
-
auto: If the context of this response and previous ones exceeds the model’s context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. -
disabled(default): If a model response will exceed the context window size for a model, the request will fail with a 400 error. Possible values:auto,disabled
The unique ID of the previous response to the model. Use this to
create multi-turn conversations. Learn more about
conversation state.
o-series models onlyConfiguration options for
reasoning models.
Controls which reasoning items are rendered back to the model on later turns, e.g.
auto, current_turn, or all_turns.o-series models onlyConstrains effort on reasoning for
reasoning models.
Currently supported values are
low, medium, and high. Reducing
reasoning effort can result in faster responses and fewer tokens used
on reasoning in a response.Possible values: low, medium, highDeprecated: use
summary instead.A summary of the reasoning performed by the model. This can be
useful for debugging and understanding the model’s reasoning process.
One of auto, concise, or detailed.Possible values: auto, concise, detailedA summary of the reasoning performed by the model. This can be
useful for debugging and understanding the model’s reasoning process.
One of
auto, concise, or detailed.Possible values: auto, concise, detailedAn object specifying the format that the model must output.Configuring
{ "type": "json_schema" } enables Structured Outputs,
which ensures the model will match your supplied JSON schema. Learn more in the
Structured Outputs guide.The default format is { "type": "text" } with no additional options.Not recommended for gpt-4o and newer models:Setting to { "type": "json_object" } enables the older JSON mode, which
ensures the message the model generates is valid JSON. Using json_schema
is preferred for models that support it.How the model should select which tool (or tools) to use when generating
a response. See the
tools parameter to see how to specify which tools
the model can call.Unix timestamp (in seconds) of when this Response was completed. Only present when the status is
completed.The error code for the response.Possible values:
server_error, rate_limit_exceeded, invalid_prompt, vector_store_timeout, invalid_image, invalid_image_format, invalid_base64_image, invalid_image_url, image_too_large, image_too_small, image_parse_error, image_content_policy_violation, invalid_image_mode, image_file_too_large, unsupported_image_media_type, empty_image_file, failed_to_download_image, image_file_not_foundModeration results for the response input and output, if moderated completions were requested.
An array of content items generated by the model.
- The length and order of items in the
outputarray is dependent on the model’s response. - Rather than accessing the first item in the
outputarray and assuming it’s anassistantmessage with the content generated by the model, you might consider using theoutput_textproperty where supported in SDKs.
SDK-only convenience property that contains the aggregated text output
from all
output_text items in the output array, if any are present.
Supported in the Python and JavaScript SDKs.Used by OpenAI to cache responses for similar requests to optimize cache hit rates. Replaces the
user field.A stable identifier used to help detect users of your application that may be violating OpenAI’s usage policies.
The status of the response generation. One of
completed, failed, in_progress, cancelled, queued, or incomplete.Possible values: completed, failed, in_progress, cancelled, queued, incompleteThe maximum number of most likely tokens to return at each token position, each with an associated log probability.
Represents token usage details including input tokens, output tokens,
a breakdown of output tokens, and the total tokens used.
The number of tokens that were retrieved from the cache.
More on prompt caching.
Examples
Input
Output
Before you ship
The SDKs create anIdempotency-Key and reuse it for automatic retries. For manual retries, reuse the original key. Router can hold the connection for up to 10 minutes.
When a request fails, Router sends an X-Comfy-Error-Type response header explaining why. A 422 means Router rejected the input before calling the provider, and a 413 means the request body was larger than Router accepts. Download generated assets promptly because result URLs can expire.
Any size limit named in a field description above is the provider’s own bound on that field, quoted from the provider’s specification. Router applies a separate cap to the whole request body, which base64-encoded media counts against: see request body size.
This page documents one partner model called through Comfy Router. The same comfy-sdk / @comfyorg/sdk package also ships a second client, for running a whole ComfyUI workflow graph on Comfy Cloud: Comfy(api_key=...) / new Comfy({ apiKey }), with client.workflows, client.assets and client.jobs. See Comfy SDKs.
Headers
Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.
Using the Router API
Model discovery, validation errors, retries, and billing.
Limitations
What Router does not do today, and what to use instead.