Create Response

modelrequiredstring

The model ID to use. See Models for available identifiers. Example: "skytells-3".

inputrequiredstring | InputItem[]

The input for this turn. Pass a plain string for a single user message, or a structured InputItem[] array for multi-modal or multi-part inputs (text + images).

// String shorthand
"What is in this image?"

// Structured array
[
  { "role": "user", "content": [
      { "type": "input_text", "text": "What is in this image?" },
      { "type": "input_image", "image_url": "https://example.com/photo.jpg" }
  ]}
]

previous_response_idstring

The id of a previous Response to continue from. When set, the server appends this request as the next turn — you do not need to resend earlier messages. Requires store: true on the prior response.

storeboolean

Whether to persist this response in the server-side conversation store. Must be true for previous_response_id chaining in future turns. Defaults to false.

streamboolean

Whether to stream the response as Server-Sent Events. Defaults to false. When true, returns a stream of ResponsesStreamEvent objects instead of a single Response.

instructionsstring

A system-level instruction prepended to the conversation. Equivalent to a system role message. Ignored if previous_response_id is set (the previous response's instructions persist).

max_output_tokensinteger

Maximum number of output tokens to generate. The request fails with a length finish reason if the model reaches this limit. Defaults to the model's maximum.

temperaturenumber

Sampling temperature, between 0 and 2. Values closer to 0 produce more deterministic output; higher values increase randomness. Defaults to 1.

top_pnumber

Nucleus sampling — only tokens within the top top_p probability mass are sampled. Values between 0 and 1. Do not set both temperature and top_p simultaneously. Defaults to 0.98.

toolsTool[]

A list of tools the model may call. Enabling tools allows the model to emit function_call output items.

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a location.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": { "type": "string" }
      },
      "required": ["location"]
    }
  }
]

tool_choicestring | object

Controls which tool (if any) the model must call. Values: "none", "auto", "required", or { "type": "function", "name": "tool_name" } to force a specific tool. Defaults to "auto" when tools are present.

userstring

An opaque identifier for the end-user. Used for abuse monitoring and rate-limit attribution. Does not affect model behavior.

truncationstring

Truncation strategy for the context window. Values: "auto" (server truncates oldest turns when the context window fills) or "disabled" (request fails if context limit is exceeded). Defaults to "disabled".

includestring[]

Additional response fields to include. Supported values: "usage", "reasoning.encrypted_content" (reasoning models). Defaults to [].

metadataobject

Up to 16 key-value string pairs attached to the response. Useful for logging and retrieval. Keys ≤ 64 characters, values ≤ 512 characters.

frequency_penaltynumber

Penalize tokens proportional to how often they have already appeared in the output. Values between -2.0 and 2.0. Positive values reduce repetition. Defaults to 0.

presence_penaltynumber

Penalize any token that has appeared at all in the output so far. Values between -2.0 and 2.0. Positive values encourage topic diversity. Defaults to 0.

parallel_tool_callsboolean

Whether the model may invoke multiple tools in a single turn. Defaults to true.

service_tierstring

Inference tier to use. "auto" lets Skytells select the optimal tier; "default" uses the standard inference layer. Defaults to "auto".

reasoningobject

Reasoning configuration for thinking models. Set effort to "none" | "low" | "medium" | "high" to control how deeply the model thinks before responding. Set summary to "auto" to include a reasoning summary in the output. Defaults to { "effort": "none", "summary": null }.

textobject

Text output format configuration. format.type accepts "text" (default) or "json_schema" for structured output. verbosity controls response length: "short" | "medium" (default) | "long".

The stream emits these event types in order:

The Responses API stores conversation context server-side. Rather than resending the full message history on every request, pass previous_response_id to continue seamlessly from where the last turn ended.

Requirements:

• Set store: true on every turn you want to chain from
• previous_response_id must be the id of a stored Response from the same model

The server reconstructs the full conversation history automatically — only new tokens from the current turn are billed.

Return type

Each turn returns a Response object. Key fields to read:

Possible errors

• INVALID_PARAMETER — previous_response_id references a response that does not exist or was not stored with store: true
• INFERENCE_ERROR — provider does not support stateful context for this model
• INFERENCE_TIMEOUT — reduce max_output_tokens or split into fewer turns

Attach a tools array to the request. When the model wants to call a tool, it returns a function_call OutputItem instead of a text message. Run the function locally, then submit the result as a function_call_output input item referencing call_id.

The agentic loop:

1. Call responses.create() with tools and store: true
2. Model returns a function_call output item with name + arguments
3. Execute the function locally
4. Submit result via function_call_output, referencing call_id and previous_response_id
5. Model replies with the final answer

Request fields

• tools — array of function definitions, each with type: "function", name, description, and parameters (JSON Schema)
• tool_choice — "auto" (default), "none", "required", or { type: "function", name } to force a specific call
• store: true — required on every turn to preserve tool call history server-side
• previous_response_id — set this on the follow-up turn (Step 2) to chain context

Response fields (Step 1)

• output[].type — will be "function_call" when the model wants to invoke a tool
• output[].name — the function name the model chose to call
• output[].arguments — JSON string of parameters to pass to your function
• output[].call_id — opaque ID you must echo back in function_call_output

Response fields (Step 2)

• Returns a normal Response with the final answer in output[0].content[0].text

Possible errors

• INVALID_PARAMETER — malformed tools array or invalid JSON Schema in parameters
• CONTENT_POLICY_VIOLATION — tool call or result blocked by safety policy
• INFERENCE_ERROR — provider does not support tool calling for this model
• INFERENCE_TIMEOUT — multi-turn agentic loops can exceed the time limit; reduce turns or max_output_tokens