DigitalOcean API (unofficial showcase)
POST/v1/responses

Send Prompt to a Model Using the Responses API

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

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

13 body fields
modelstringrequired
The model ID of the model you want to use. Get the model ID using `/v1/models` or on the available models page.
inputstringrequired
The prompt or input content you want the model to respond to. Can be a simple text string or an array of message objects for conversation context.
max_output_tokensintegeroptional
The maximum number of tokens to generate in the response.
temperaturenumberoptional
A value between 0.0 and 2.0 to control randomness and creativity. Lower values like 0.2 make the output more focused and deterministic, while higher values like 0.8 make it more random.
streambooleanoptional
Set to true to stream partial responses as Server-Sent Events.
Default:false
instructionsstringoptional
System-level instructions for the model. This sets the behavior and context for the response generation.
top_pnumberoptional
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.
stream_optionsobjectoptional
Options for streaming response. Only set this when you set stream to true.
Default:null
toolsarray<object>optional
A list of tools the model may call.
tool_choicestringoptional
Controls which (if any) tool is called by the model.
Allowed:noneautorequired
stopstringoptional
Up to 4 sequences where the API will stop generating further tokens.
Default:null
metadataobjectoptional
Set of key-value pairs that can be attached to the request.
userstringoptional
A unique identifier representing your end-user.

5 status codes
200Successful response. When stream is true, response is sent as Server-Sent Events (text/event-stream); otherwise a single JSON object (application/json) is returned.
idstringrequired
A unique identifier for the response.
objectstringrequired
The object type, which is always `response`.
Allowed:response
createdintegerrequired
The Unix timestamp (in seconds) of when the response was created.
modelstringrequired
The model used to generate the response.
outputarray<object>required
An array of content items generated by the model. Each item has a type and a content array. Types include reasoning and output text.
usageobjectrequired
Detailed usage statistics for the Responses API request, including input/output token counts and detailed breakdowns.
parallel_tool_callsbooleanoptional
Whether parallel tool calls are enabled.
temperaturenumberoptional
Temperature setting used for the response.
tool_choicestringoptional
Tool choice setting used for the response.
toolsarray<object>optional
Tools available for the response.
top_pnumberoptional
Top-p setting used for the response.
max_output_tokensintegeroptional
Maximum output tokens setting.
statusstringoptional
Status of the response.
userstringoptional
User identifier.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned: Authentication failed due to invalid credentials. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.