For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Usage

inferenceClient.responses.create(params: Record<string, any>, streamCallbacks?: InferenceStreamCallbacks): Promise<any>

Description

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

Parameters

model string required

Example: openai-gpt-oss-20b

The model ID of the model you want to use. Get the model ID using /v1/models or on the available models page.

input string or array of objects required

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_tokens integer or null optional

Example: 50

The maximum number of tokens to generate in the response.

Min: 1

temperature number or null optional

Example: 0.7

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.

Min: 0

Max: 2

stream boolean or null optional

Example: false

Set to true to stream partial responses as Server-Sent Events.

Default: false

instructions string or null optional

Example: You are a helpful assistant.

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

top_p number or null optional

Example: 1

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.

Min: 0

Max: 1

stream_options object or null optional

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

Show child properties

include_usage boolean optional

Example: true

If set, an additional chunk will be streamed before the data: [DONE] message with token usage statistics for the entire request.

tools array of objects or null optional

A list of tools the model may call.

Show child properties

type string required

Example: function

The type of the tool.

name string optional

Example: get_weather

The name of the function to be called.

description string optional

Example: Get the current weather in a given location.

A description of what the function does.

parameters object optional

The parameters the function accepts, described as a JSON Schema object.

tool_choice string or object optional

Controls which (if any) tool is called by the model.

Show child properties

type string optional

Example: function

function object optional

Additional nested properties are not shown.

stop string or array of strings or null optional

Up to 4 sequences where the API will stop generating further tokens.

metadata object or null optional

Example: {"session_id": "abc123"}

Set of key-value pairs that can be attached to the request.

user string or null optional

Example: user-1234

A unique identifier representing your end-user.

Request Sample

import { InferenceClient } from "@digitalocean/dots";

const inferenceClient = new InferenceClient({
    apiKey: process.env.MODEL_ACCESS_KEY!,
});

const response = await inferenceClient.responses.create({
    model: "openai-gpt-oss-20b",
    input: "What is the capital of France?",
    max_output_tokens: 50,
    temperature: 0.7,
    stream: false,
    instructions: "You are a helpful assistant.",
    top_p: 1,
    stream_options: {
        include_usage: true,
    },
    tools: [
        {
            type: "function",
            name: "get_weather",
            description: "Get the current weather in a given location.",
        },
    ],
    tool_choice: "auto",
    stop: "\n",
    metadata: {
        session_id: "abc123",
    },
    user: "user-1234",
});

Response Example

{
  "id": "response-abc123def456",
  "object": "response",
  "created": 1721596428,
  "model": "openai-gpt-oss-20b",
  "output": [
    {
      "type": "message",
      "id": "item_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [],
      "call_id": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"location\": \"San Francisco\"}"
    }
  ],
  "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
  },
  "parallel_tool_calls": false,
  "temperature": 0.7,
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather in a given location."
    }
  ],
  "top_p": 1,
  "max_output_tokens": 50,
  "status": "completed",
  "user": "user-1234"
}

More Information

See /v1/responses in the API reference for additional detail on responses, headers, parameters, and more.