Creates a text-to-text response

client.Responses.New(ctx, body) (*CreateResponseResponse, error)

post/responses

Generate text responses from text prompts. This endpoint supports both streaming and non-streaming responses for VLLM models only.

ParametersExpand Collapse

body ResponseNewParams

Input param.Field[ResponseNewParamsInputUnion]

The input text prompt or conversation history. Can be a string or an array of message objects for conversation context.

UnionString

ResponseNewParamsInputArray

Accepts one of the following:

ResponseNewParamsInputArrayObject

Type ResponseNewParamsInputArrayObjectType

The type of input item (must be function_call, function_call_output, or reasoning)

Accepts one of the following:

const ResponseNewParamsInputArrayObjectTypeFunctionCall ResponseNewParamsInputArrayObjectType = "function_call"

const ResponseNewParamsInputArrayObjectTypeFunctionCallOutput ResponseNewParamsInputArrayObjectType = "function_call_output"

const ResponseNewParamsInputArrayObjectTypeReasoning ResponseNewParamsInputArrayObjectType = "reasoning"

ID stringoptional

The unique ID of the reasoning item (optional for reasoning)

Arguments stringoptional

JSON string of function arguments (required for function_call)

CallID stringoptional

The call ID (required for function_call and function_call_output)

Content []ResponseNewParamsInputArrayObjectContentoptional

Array of reasoning content parts (optional for reasoning, can be null)

Text stringoptional

The reasoning text content

Type ResponseNewParamsInputArrayObjectContentTypeoptional

The type of content

Accepts one of the following:

const ResponseNewParamsInputArrayObjectContentTypeReasoningText ResponseNewParamsInputArrayObjectContentType = "reasoning_text"

EncryptedContent stringoptional

Encrypted content (optional)

Name stringoptional

The function name (required for function_call)

Output stringoptional

JSON string of function output (required for function_call_output)

Status stringoptional

Status of the item (optional, can be null)

Summary []unknownoptional

Summary of the reasoning (optional for reasoning)

ResponseNewParamsInputArrayObject

Content ResponseNewParamsInputArrayObjectContentUnion

The content of the message (string or content parts array)

Accepts one of the following:

UnionString

ResponseNewParamsInputArrayObjectContentArray

Accepts one of the following:

ResponseNewParamsInputArrayObjectContentArrayObject

Text string

The text content

Type ResponseNewParamsInputArrayObjectContentArrayObjectType

The type of content part

Accepts one of the following:

const ResponseNewParamsInputArrayObjectContentArrayObjectTypeInputText ResponseNewParamsInputArrayObjectContentArrayObjectType = "input_text"

ResponseNewParamsInputArrayObjectContentArrayMap

Role ResponseNewParamsInputArrayObjectRoleoptional

The role of the message author

Accepts one of the following:

const ResponseNewParamsInputArrayObjectRoleUser ResponseNewParamsInputArrayObjectRole = "user"

const ResponseNewParamsInputArrayObjectRoleAssistant ResponseNewParamsInputArrayObjectRole = "assistant"

const ResponseNewParamsInputArrayObjectRoleSystem ResponseNewParamsInputArrayObjectRole = "system"

const ResponseNewParamsInputArrayObjectRoleTool ResponseNewParamsInputArrayObjectRole = "tool"

const ResponseNewParamsInputArrayObjectRoleDeveloper ResponseNewParamsInputArrayObjectRole = "developer"

ToolCallID stringoptional

Tool call ID that this message is responding to (required for tool role)

ToolCalls []ResponseNewParamsInputArrayObjectToolCalloptional

Tool calls made by the assistant (for assistant role messages)

ID string

The ID of the tool call.

Function ResponseNewParamsInputArrayObjectToolCallsFunction

The function that the model called.

Arguments string

The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

Name string

The name of the function to call.

Type ResponseNewParamsInputArrayObjectToolCallsType

The type of the tool. Currently, only function is supported.

Accepts one of the following:

const ResponseNewParamsInputArrayObjectToolCallsTypeFunction ResponseNewParamsInputArrayObjectToolCallsType = "function"

Type ResponseNewParamsInputArrayObjectTypeoptional

Optional type identifier for message items (used by some clients like Codex)

Accepts one of the following:

const ResponseNewParamsInputArrayObjectTypeMessage ResponseNewParamsInputArrayObjectType = "message"

Model param.Field[string]

Model ID used to generate the response. Must be a VLLM model.

Instructions param.Field[string]optional

System-level instructions for the model. This sets the behavior and context for the response generation.

MaxOutputTokens param.Field[int64]optional

Maximum number of tokens to generate in the response. If not specified, the model will use a default value.

minimum1

MaxTokens param.Field[int64]optional

The maximum number of tokens that can be generated in the completion. Alias for max_output_tokens for compatibility.

minimum0

Metadata param.Field[map[string, string]]optional

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Modalities param.Field[[]ResponseNewParamsModality]optional

Specifies the output types the model should generate. For text-to-text, this should be ["text"].

const ResponseNewParamsModalityText ResponseNewParamsModality = "text"

ParallelToolCalls param.Field[bool]optional

Whether to enable parallel tool calls. When true, the model can make multiple tool calls in parallel.

Stop param.Field[ResponseNewParamsStopUnion]optional

Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.

UnionString

ResponseNewParamsStopArray

StreamOptions param.Field[ResponseNewParamsStreamOptions]optional

Options for streaming response. Only set this when you set stream: true.

IncludeUsage booloptional

If set, an additional chunk will be streamed before the data: [DONE] message. The usage field on this chunk shows the token usage statistics for the entire request, and the choices field will always be an empty array.

All other chunks will also include a usage field, but with a null value. NOTE: If the stream is interrupted, you may not receive the final usage chunk which contains the total token usage for the request.

Temperature param.Field[float64]optional

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

minimum0

maximum2

ToolChoice param.Field[ResponseNewParamsToolChoiceUnion]optional

Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools. Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.

none is the default when no tools are present. auto is the default if tools are present.

ResponseNewParamsToolChoiceString

Accepts one of the following:

const ResponseNewParamsToolChoiceStringNone ResponseNewParamsToolChoiceString = "none"

const ResponseNewParamsToolChoiceStringAuto ResponseNewParamsToolChoiceString = "auto"

const ResponseNewParamsToolChoiceStringRequired ResponseNewParamsToolChoiceString = "required"

ResponseNewParamsToolChoiceChatCompletionNamedToolChoice

Function ResponseNewParamsToolChoiceChatCompletionNamedToolChoiceFunction

Name string

The name of the function to call.

Type ResponseNewParamsToolChoiceChatCompletionNamedToolChoiceType

The type of the tool. Currently, only function is supported.

Accepts one of the following:

const ResponseNewParamsToolChoiceChatCompletionNamedToolChoiceTypeFunction ResponseNewParamsToolChoiceChatCompletionNamedToolChoiceType = "function"

Tools param.Field[[]ResponseNewParamsTool]optional

A list of tools the model may call. Currently, only functions are supported as a tool. Uses Responses API format (with name, description, parameters at top level).

Type ResponseNewParamsToolsType

The type of the tool. Supported values are function (custom tools), web_search, and web_search_2025_08_26 (built-in web search).

Accepts one of the following:

const ResponseNewParamsToolsTypeFunction ResponseNewParamsToolsType = "function"

const ResponseNewParamsToolsTypeWebSearch ResponseNewParamsToolsType = "web_search"

const ResponseNewParamsToolsTypeWebSearch2025_08_26 ResponseNewParamsToolsType = "web_search_2025_08_26"

Description stringoptional

A description of what the function does, used by the model to choose when and how to call the function.

Name stringoptional

The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Parameters map[string, unknown]optional

The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.

TopP param.Field[float64]optional

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

minimum0

maximum1

User param.Field[string]optional

A unique identifier representing your end-user, which can help DigitalOcean to monitor and detect abuse.

ReturnsExpand Collapse

type CreateResponseResponse struct{…}

Represents a text-to-text response returned by the model, based on the provided input. VLLM models only.

ID string

A unique identifier for the response.

Created int64

The Unix timestamp (in seconds) of when the response was created.

Model string

The model used to generate the response.

Object CreateResponseResponseObject

The object type, which is always response.

Accepts one of the following:

const CreateResponseResponseObjectResponse CreateResponseResponseObject = "response"

Usage CreateResponseResponseUsage

Detailed token usage statistics for the request, including input/output token counts and detailed breakdowns.

InputTokens int64

The number of input tokens.

InputTokensDetails CreateResponseResponseUsageInputTokensDetails

A detailed breakdown of the input tokens.

CachedTokens int64

The number of tokens that were retrieved from the cache. More on prompt caching.

OutputTokens int64

The number of output tokens.

OutputTokensDetails CreateResponseResponseUsageOutputTokensDetails

A detailed breakdown of the output tokens.

ReasoningTokens int64

The number of reasoning tokens.

ToolOutputTokens int64

The number of tool output tokens.

TotalTokens int64

The total number of tokens used.

Background booloptional

Whether the request was processed in the background

Choices []CreateResponseResponseChoiceoptional

A list of response choices. Can be more than one if n is greater than 1. Optional - Responses API primarily uses the output array.

FinishReason CreateResponseResponseChoicesFinishReason

The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, length if the maximum number of tokens specified in the request was reached, or tool_calls if the model called a tool.

Accepts one of the following:

const CreateResponseResponseChoicesFinishReasonStop CreateResponseResponseChoicesFinishReason = "stop"

const CreateResponseResponseChoicesFinishReasonLength CreateResponseResponseChoicesFinishReason = "length"

const CreateResponseResponseChoicesFinishReasonToolCalls CreateResponseResponseChoicesFinishReason = "tool_calls"

const CreateResponseResponseChoicesFinishReasonContentFilter CreateResponseResponseChoicesFinishReason = "content_filter"

Index int64

The index of the choice in the list of choices.

Message CreateResponseResponseChoicesMessage

The generated message response.

Content stringoptional

The generated text content.

Role CreateResponseResponseChoicesMessageRoleoptional

The role of the message author, which is always assistant.

Accepts one of the following:

const CreateResponseResponseChoicesMessageRoleAssistant CreateResponseResponseChoicesMessageRole = "assistant"

ToolCalls []CreateResponseResponseChoicesMessageToolCalloptional

The tool calls generated by the model, such as function calls.

ID string

The ID of the tool call.

Function CreateResponseResponseChoicesMessageToolCallsFunction

The function that the model called.

Arguments string

Name string

The name of the function to call.

Type CreateResponseResponseChoicesMessageToolCallsType

The type of the tool. Currently, only function is supported.

Accepts one of the following:

const CreateResponseResponseChoicesMessageToolCallsTypeFunction CreateResponseResponseChoicesMessageToolCallsType = "function"

Logprobs CreateResponseResponseChoicesLogprobsoptional

Log probability information for the choice. Only present if logprobs was requested in the request.

Content []ChatCompletionTokenLogprob

A list of message content tokens with log probability information.

Token string

The token.

Bytes []int64

A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be null if there is no bytes representation for the token.

Logprob float64

The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

TopLogprobs []ChatCompletionTokenLogprobTopLogprob

List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested top_logprobs returned.

Token string

The token.

Bytes []int64

Logprob float64

The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value -9999.0 is used to signify that the token is very unlikely.

InputMessages []unknownoptional

Input messages (if applicable)

MaxOutputTokens int64optional

Maximum output tokens setting

MaxToolCalls int64optional

Maximum tool calls setting

Output []CreateResponseResponseOutputoptional

An array of content items generated by the model. This includes text content, function calls, reasoning items, and other output types. Use this field for Responses API compatibility.

Accepts one of the following:

type CreateResponseResponseOutputObject struct{…}

Arguments string

JSON string of function arguments

CallID string

The unique ID of the function tool call

Name string

The name of the function to call

Type CreateResponseResponseOutputObjectType

The type of output item

Accepts one of the following:

const CreateResponseResponseOutputObjectTypeFunctionCall CreateResponseResponseOutputObjectType = "function_call"

ID stringoptional

The unique ID of the function tool call (same as call_id)

EncryptedContent stringoptional

Encrypted content (optional)

Status stringoptional

Status of the item (optional, can be null)

type CreateResponseResponseOutputObject struct{…}

Text string

The text content

Type CreateResponseResponseOutputObjectType

The type of output item

Accepts one of the following:

const CreateResponseResponseOutputObjectTypeText CreateResponseResponseOutputObjectType = "text"

type CreateResponseResponseOutputObject struct{…}

ID string

The unique ID of the reasoning item

Content []CreateResponseResponseOutputObjectContent

Array of reasoning content parts

Text string

The reasoning text content

Type CreateResponseResponseOutputObjectContentType

The type of content

Accepts one of the following:

const CreateResponseResponseOutputObjectContentTypeReasoningText CreateResponseResponseOutputObjectContentType = "reasoning_text"

Summary []unknown

Summary of the reasoning (usually empty)

Type CreateResponseResponseOutputObjectType

The type of output item

Accepts one of the following:

const CreateResponseResponseOutputObjectTypeReasoning CreateResponseResponseOutputObjectType = "reasoning"

EncryptedContent stringoptional

Encrypted content (optional)

Status stringoptional

Status of the item (optional, can be null)

OutputMessages []unknownoptional

Output messages (if applicable)

ParallelToolCalls booloptional

Whether parallel tool calls are enabled

PreviousResponseID stringoptional

Previous response ID (for multi-turn conversations)

Prompt stringoptional

Prompt used for the response

Reasoning stringoptional

Reasoning content

ServiceTier stringoptional

Service tier used

Status stringoptional

Status of the response

Temperature float64optional

Temperature setting used for the response

Text stringoptional

Text content

ToolChoice stringoptional

Tool choice setting used for the response

Tools []CreateResponseResponseTooloptional

Tools available for the response

Type CreateResponseResponseToolsType

The type of the tool. Supported values are function (custom tools), web_search, and web_search_2025_08_26 (built-in web search).

Accepts one of the following:

const CreateResponseResponseToolsTypeFunction CreateResponseResponseToolsType = "function"

const CreateResponseResponseToolsTypeWebSearch CreateResponseResponseToolsType = "web_search"

const CreateResponseResponseToolsTypeWebSearch2025_08_26 CreateResponseResponseToolsType = "web_search_2025_08_26"

Description stringoptional

A description of what the function does, used by the model to choose when and how to call the function.

Name stringoptional

The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

Parameters map[string, unknown]optional

The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.

Omitting parameters defines a function with an empty parameter list.

TopLogprobs int64optional

Top logprobs setting

TopP float64optional

Top-p setting used for the response

Truncation stringoptional

Truncation setting

User stringoptional

User identifier

Creates a text-to-text response

package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/-go"
  "github.com/stainless-sdks/-go/option"
  "github.com/stainless-sdks/-go/shared"
)

func main() {
  client := gradient.NewClient(
    option.WithModelAccessKey("My Model Access Key"),
  )
  createResponseResponse, err := client.Responses.New(context.TODO(), gradient.ResponseNewParams{
    Input: gradient.F[gradient.ResponseNewParamsInputUnion](shared.UnionString("Tell me a three-sentence bedtime story about a unicorn.")),
    Model: gradient.F("llama3-8b-instruct"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", createResponseResponse.ID)
}

{
  "id": "response-abc123def456",
  "created": 1721596428,
  "model": "llama3-8b-instruct",
  "object": "response",
  "usage": {
    "input_tokens": 133,
    "input_tokens_details": {
      "cached_tokens": 128
    },
    "output_tokens": 41,
    "output_tokens_details": {
      "reasoning_tokens": 24,
      "tool_output_tokens": 0
    },
    "total_tokens": 174
  },
  "background": true,
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Once upon a time, a unicorn named Sparkle...",
        "role": "assistant",
        "tool_calls": [
          {
            "id": "id",
            "function": {
              "arguments": "arguments",
              "name": "name"
            },
            "type": "function"
          }
        ]
      },
      "logprobs": {
        "content": [
          {
            "token": "token",
            "bytes": [
              0
            ],
            "logprob": 0,
            "top_logprobs": [
              {
                "token": "token",
                "bytes": [
                  0
                ],
                "logprob": 0
              }
            ]
          }
        ]
      }
    }
  ],
  "input_messages": [
    {}
  ],
  "max_output_tokens": 0,
  "max_tool_calls": 0,
  "output": [
    {
      "arguments": "arguments",
      "call_id": "call_id",
      "name": "name",
      "type": "function_call",
      "id": "id",
      "encrypted_content": "encrypted_content",
      "status": "status"
    }
  ],
  "output_messages": [
    {}
  ],
  "parallel_tool_calls": true,
  "previous_response_id": "previous_response_id",
  "prompt": "prompt",
  "reasoning": "reasoning",
  "service_tier": "service_tier",
  "status": "status",
  "temperature": 0,
  "text": "text",
  "tool_choice": "tool_choice",
  "tools": [
    {
      "type": "function",
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      }
    }
  ],
  "top_logprobs": 0,
  "top_p": 0,
  "truncation": "truncation",
  "user": "user"
}

Returns Examples

{
  "id": "response-abc123def456",
  "created": 1721596428,
  "model": "llama3-8b-instruct",
  "object": "response",
  "usage": {
    "input_tokens": 133,
    "input_tokens_details": {
      "cached_tokens": 128
    },
    "output_tokens": 41,
    "output_tokens_details": {
      "reasoning_tokens": 24,
      "tool_output_tokens": 0
    },
    "total_tokens": 174
  },
  "background": true,
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Once upon a time, a unicorn named Sparkle...",
        "role": "assistant",
        "tool_calls": [
          {
            "id": "id",
            "function": {
              "arguments": "arguments",
              "name": "name"
            },
            "type": "function"
          }
        ]
      },
      "logprobs": {
        "content": [
          {
            "token": "token",
            "bytes": [
              0
            ],
            "logprob": 0,
            "top_logprobs": [
              {
                "token": "token",
                "bytes": [
                  0
                ],
                "logprob": 0
              }
            ]
          }
        ]
      }
    }
  ],
  "input_messages": [
    {}
  ],
  "max_output_tokens": 0,
  "max_tool_calls": 0,
  "output": [
    {
      "arguments": "arguments",
      "call_id": "call_id",
      "name": "name",
      "type": "function_call",
      "id": "id",
      "encrypted_content": "encrypted_content",
      "status": "status"
    }
  ],
  "output_messages": [
    {}
  ],
  "parallel_tool_calls": true,
  "previous_response_id": "previous_response_id",
  "prompt": "prompt",
  "reasoning": "reasoning",
  "service_tier": "service_tier",
  "status": "status",
  "temperature": 0,
  "text": "text",
  "tool_choice": "tool_choice",
  "tools": [
    {
      "type": "function",
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      }
    }
  ],
  "top_logprobs": 0,
  "top_p": 0,
  "truncation": "truncation",
  "user": "user"
}