OpenAI Response Protocol Field Descriptions

Download

フォーカスモード

フォントサイズ

最終更新日: 2026-08-14 18:39:39

AI翻訳

Using the OpenAI Responses API
Request Body Parameters
Basic Parameters
Parameter
Type
Required
Description
model
string
No
The model ID used to generate the response, such as hy3.
input
string or array
No
The text, image, or file input sent to the model. A string represents plain text (equivalent to the text of the user role). An array represents a list of input items. For details, see Input Type Details.
instructions
string
No
A system (or developer) message inserted into the model context. When the system message is used with previous_response_id, the instructions from the previous response do not carry over to the next response, facilitating the replacement of system messages.
stream
boolean
No
When set to true, the model response data is streamed via SSE, with events including response.created, response.output_text.delta, response.completed, and others.
Generation Control Parameters
Parameter
Type
Value Range
Description
max_output_tokens
number
≥ 1
The maximum number of tokens that can be generated in a response, including visible output tokens and reasoning tokens. Reasoning tokens from the reasoning model are also counted toward this limit.
temperature
number
[0, 2]
Sampling temperature, which controls the randomness of the output. A higher value makes the output more random and creative, while a lower value makes it more focused and deterministic.
top_p
number
(0, 1]
Nucleus sampling parameter. The model only considers tokens with the top top_p probability mass. It is recommended to adjust only one of temperature or top_p.
truncation
string
"auto" / "disabled"
The truncation policy when the context exceeds the model's maximum length. auto deletes entries from the beginning of the conversation; disabled (default) causes the request to fail with a 400 error when the limit is exceeded. All three models accept this parameter but do not echo it in the response body.
Tool Call
Parameter
Type
Description
tools
array
An array of tools that the model can call when the model is generating responses. Supports function calling, file search, web search, and more. For details, see Tool Types Explained.
tool_choice
string or object
How the model selects tools. For the specific values, see the table below.
parallel_tool_calls
boolean
Whether to allow the model to run tool calls in parallel.
tool_choice Valid values:
Value/Type
Description
"none"
The model does not call any tools and directly generates a message.
"auto"
The model can choose to generate a message or call one or more tools.
{ "type": "function", "name": "..." }
Forces the model to call a specific function.
{ "type": "mcp", "server_label": "...", "name": "..." }
Forces the model to call a tool on a specific MCP server.
 Attention:
tool_choice "required" and support for specifying function objects vary by model:
deepseek-v4-flash and deepseek-v4-pro: Thinking mode is enabled by default. When thinking mode is enabled, passing "required" or a function object returns a 400 error. To force a tool call, explicitly disable thinking mode first.
hy3: "required" and specifying function objects are not currently supported. Use "auto" or "none" instead.
Support for "required" is ultimately determined by the invoked model itself. If an error is returned, use "auto" instead or directly specify the concrete tool name.
Output Format Control
text parameter (object): Configures the text format for model output by specifying the text.format subfield.
Format Type
Description
{ "type": "text" }
The default format that generates text responses.
{ "type": "json_schema", "name": "...", "schema": {...} }
Structured output that ensures the model output conforms to the specified JSON Schema.
{ "type": "json_object" }
The legacy JSON mode that ensures the output is valid JSON (not recommended for new models).
 Attention:
When json_schema or json_object is used, hy3 and deepseek-v4-flash strictly output pure JSON. Additionally, the schema for json_schema must include "additionalProperties": false; otherwise, hy3 returns an error.
include parameter (array): Specifies a list of additional fields to include in the response. All three models accept this parameter, but whether the additional fields are actually returned depends on model support.
Value
Description
file_search_call.results
Contains the search results from the file search tool call.
web_search_call.results
Contains the results from the web search tool call.
message.input_image.image_url
Contains the image URL from the input message.
code_interpreter_call.outputs
Contains the output from the code interpreter execution.
reasoning.encrypted_content
Contains the encrypted version of reasoning tokens, used for stateless multi-turn conversations.
message.output_text.logprobs
Contains the log probabilities of the assistant message.
Inference Control
reasoning parameter (object): A configuration option applicable only to reasoning models.
Field
Type
Description
effort
"none" / "low" / "medium" / "high"
Constraints on reasoning effort. Reducing reasoning effort can decrease response time and reasoning Token consumption.
summary
"auto" / "concise" / "detailed"
A summary of the model reasoning process, used for debugging and understanding the reasoning process.
Conversation Management
previous_response_id parameter (string): The ID of the previous response, used for multi-turn conversations. It maintains conversation state by linking response IDs, eliminating the need to manually manage message history. It cannot be used concurrently with conversation.
Note:
Model Support: hy3 and models accessed through compatibility mode (such as deepseek-v4-flash, deepseek-v4-pro, glm-5.2, kimi-k3 and so on) do not support this feature. Passing a non-empty value returns a 400 error: previous_response_id is not supported in chat-compat mode. For multi-turn conversations, pass the complete conversation history through the input array.
Other parameters
Parameter
Type
Description
background
boolean
Whether to run asynchronously in the background. All models accept this parameter, but all actually return synchronously.
store
boolean
Whether to store responses for subsequent search. All three models accept this parameter (without error), but do not actually echo it.
metadata
object
Key-value pair metadata attached to the response (maximum of 16 pairs, key length ≤ 64 characters, value length ≤ 512 characters). All three models accept this parameter but do not echo it in the response body.
service_tier
string
Service tier: auto / default / flex / scale / priority.
Input Type Details
When input is an array, each element is an input entry and supports the following types:
EasyInputMessage:
Field
Type
Description
content
string or array
Text, image, or audio input, which can also include previous assistant responses.
role
"user" / "assistant" / "system" / "developer"
Message role. Instructions from developer or system take precedence over those from user.
phase
"commentary" / "final_answer"
Optional. Marks an assistant message as an intermediate commentary or a final answer.
type
"message"
Optional. Message input type, always message.
ResponseInputImage:
Field
Type
Description
detail
"low" / "high" / "auto" / "original"
Image detail level, with auto as the default.
type
"input_image"
Type, always input_image.
file_id
string
Optional. File ID.
image_url
string
Optional. Image URL or base64-encoded data URL.
ResponseInputFile:
Field
Type
Description
type
"input_file"
Type, always input_file.
file_data
string
Optional. File content (base64-encoded).
file_id
string
Optional. File ID.
file_url
string
Optional. File URL.
filename
string
Optional. Filename.
Tool Type Details
Function (Function Tool):
Field
Type
Description
type
"function"
The type, which is always function.
name
string
Name of the function
parameters
object
A JSON Schema object that describes function parameters.
strict
boolean
Whether to enforce strict parameter validation. The default value is true.
description
string
Optional. Description of the function, for the model to determine whether to call it.
FileSearch (File Search Tool): Valid vector_store_ids must be provided.
When no valid vector_store_ids are configured, the request does not return an error but also does not perform a search. The model will answer directly based on its own knowledge. Models accessed through compatibility mode (such as deepseek-v4-flash, deepseek-v4-pro, glm-5.2, kimi-k3, and so on) only support function-type tools. Built-in tools like file_search, web_search, and code_interpreter are automatically discarded without error.
Field
Type
Description
type
"file_search"
Type, always file_search.
vector_store_ids
array of string
List of vector store IDs to search.
max_num_results
number
Optional. The maximum number of results to return, ranging from 1-50.
filters
ComparisonFilter or CompoundFilter
Optional. Filter conditions. For details, see Filter Types.
Return Value Details
Returns a Response object.
{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "completed_at": 1741476543,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "<your-model-name>",
  "output": [...],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 11,
    "total_tokens": 31
  }
}
Field
Type
Description
id
string
The unique identifier of the response.
object
"response"
The object type, which is always response.
created_at
number
The Unix timestamp (in seconds) when the response was created.
status
string
The status of the response: completed / incomplete / failed / in_progress / cancelled.
completed_at
number
The Unix timestamp (in seconds) when the response was completed.
error
object
The error object returned when the request fails. It is not returned upon successful completion.
incomplete_details
object
Details when the response is truncated. The reason field can be "max_output_tokens" or "content_filter".
instructions
string
The system message passed in the request, echoed as is.
max_output_tokens
number
The maximum number of output tokens specified in the request. Not returned if not specified.
model
string
The model ID used to generate the response.
output
array
A list of output entries generated by the model. For details, see Output Entry Types.
parallel_tool_calls
boolean or null
Whether to allow parallel tool calls.
previous_response_id
string
The ID of the previous response in a multi-turn conversation. Not returned for single-turn conversations.
usage
object
Token consumption statistics. For details, see the ResponseUsage object.
service_tier
string
The service tier that was actually used.
﻿ResponseUsage Object:
﻿
Field
Type
Description
input_tokens
number
The number of input tokens.
input_tokens_details
object
Details of input tokens, including cached_tokens
output_tokens
number
The number of output tokens.
output_tokens_details
object
Details of output tokens, including reasoning_tokens
total_tokens
number
The total number of tokens (input + output).
﻿Output Entry Type ( output Array):
﻿
ResponseOutputMessage (Message Output):
Field
Type
Description
id
string
The unique ID of the output message.
type
"message"
Type, always message.
role
"assistant"
Role, always assistant
status
"in_progress" / "completed" / "incomplete"
Message status.
content
array
An array of message content. Each item contains the type: "output_text" and text fields.
FunctionCall (Function Call Output):
Field
Type
Description
id
string
Unique ID.
type
"function_call"
The type, which is always function_call.
call_id
string
The function call ID, which must be passed in when function_call_output is submitted.
name
string
The name of the function being called.
arguments
string
A JSON string of function parameters.
status
string
in_progress / completed / incomplete.
ReasoningItem (Reasoning Entry): Reasoning models (hy3, deepseek-v4-flash, deepseek-v4-pro) return this entry additionally in the output when reasoning.effort is passed.
Field
Type
Description
id
string
Unique ID.
type
"reasoning"
The type, which is always reasoning.
summary
array
A list of reasoning summary texts. Each item contains the type: "summary_text" and text fields.
status
string
Status.
Example
Example: Text Input
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "input": "Tell me a three-sentence bedtime story about a unicorn."
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    input="Tell me a three-sentence bedtime story about a unicorn.",
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  input: 'Tell me a three-sentence bedtime story about a unicorn.',
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class TextInput {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "input": "Tell me a three-sentence bedtime story about a unicorn."
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "input": "Tell me a three-sentence bedtime story about a unicorn."
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Response Example:
{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "status": "completed",
  "model": "<your-model-name>",
  "output": [
    {
      "type": "message",
      "id": "msg_20260614212356mlaob0d2",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "I am Hunyuan, a large model developed by Tencent.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 11,
    "total_tokens": 31
  }
}
Example: Image Input
Note:
The image URL must be a direct link accessible via a public network. A 400 error is returned when the URL is inaccessible. Alternatively, you can use Base64 data in the format of data:image/png;base64,....
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "What is in this picture?" },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.jpg"
          }
        ]
      }
    ]
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What is in this picture?"},
                {"type": "input_image", "image_url": "https://example.com/image.jpg"},
            ],
        }
    ],
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  input: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'What is contained in this picture?' },
        { type: 'input_image', image_url: 'https://example.com/image.jpg' },
      ],
    },
  ],
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class ImageInput {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "input": [
            {
              "role": "user",
              "content": [
                { "type": "input_text", "text": "What is contained in this picture?" },
                { "type": "input_image", "image_url": "https://example.com/image.jpg" }
              ]
            }
          ]
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What is contained in this picture?" },
        { "type": "input_image", "image_url": "https://example.com/image.jpg" }
      ]
    }
  ]
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Example: File Input
Note:
File Input (input_file): The file URL must be a direct link accessible via a public network.
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "What content is contained in this file?" },
          {
            "type": "input_file",
            "file_url": "https://www.example.com/document.pdf"
          }
        ]
      }
    ]
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "What content is in this file?"},
                {"type": "input_file", "file_url": "https://www.example.com/document.pdf"},
            ],
        }
    ],
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  input: [
    {
      role: 'user',
      content: [
        { type: 'input_text', text: 'What content is in this file?' },
        { type: 'input_file', file_url: 'https://www.example.com/document.pdf' },
      ],
    },
  ],
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class FileInput {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "input": [
            {
              "role": "user",
              "content": [
                { "type": "input_text", "text": "What content is in this file?" },
                { "type": "input_file", "file_url": "https://www.example.com/document.pdf" }
              ]
            }
          ]
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What content does this file contain?" },
        { "type": "input_file", "file_url": "https://www.example.com/document.pdf" }
      ]
    }
  ]
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Example: File Search
Note:
Valid vector_store_ids must be provided. When non-existent vector_store_ids are passed, no error is reported, but no search is performed.
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "tools": [{
      "type": "file_search",
      "vector_store_ids": ["vs_1234567890"],
      "max_num_results": 20
    }],
    "input": "What are the attributes of the Ancient Brown Dragon?"
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    tools=[
        {
            "type": "file_search",
            "vector_store_ids": ["vs_1234567890"],
            "max_num_results": 20,
        }
    ],
    input="What are the attributes of the Ancient Brown Dragon?",
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  tools: [
    {
      type: 'file_search',
      vector_store_ids: ['vs_1234567890'],
      max_num_results: 20,
    },
  ],
  input: 'What are the attributes of the Ancient Brown Dragon?',
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class FileSearch {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "tools": [{
            "type": "file_search",
            "vector_store_ids": ["vs_1234567890"],
            "max_num_results": 20
          }],
          "input": "What are the attributes of the Ancient Brown Dragon?"
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "tools": [{
    "type": "file_search",
    "vector_store_ids": ["vs_1234567890"],
    "max_num_results": 20
  }],
  "input": "What are the attributes of the Ancient Brown Dragon?"
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Example: Streaming Output
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "instructions": "You are a helpful assistant.",
    "input": "Hello!",
    "stream": true
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
stream = client.responses.create(
    model="<your-model-name>",
    instructions="You are a helpful assistant.",
    input="Hello!",
    stream=True,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const stream = await client.responses.create({
  model: '<your-model-name>',
  instructions: 'You are a helpful assistant.',
  input: 'Hello!',
  stream: true,
});
for await (const event of stream) {
  if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
}
import okhttp3.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;
﻿
public class StreamResponse {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "instructions": "You are a helpful assistant.",
          "input": "Hello!",
          "stream": true
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute();
             BufferedReader reader = new BufferedReader(
                 new InputStreamReader(response.body().byteStream()))) {
            String line;
            while ((line = reader.readLine()) != null) {
                if (!line.isEmpty()) System.out.println(line);
            }
        }
    }
}
package main
﻿
import (
    "bufio"
    "fmt"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "instructions": "You are a helpful assistant.",
  "input": "Hello!",
  "stream": true
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    scanner := bufio.NewScanner(resp.Body)
    for scanner.Scan() {
        if line := scanner.Text(); line != "" {
            fmt.Println(line)
        }
    }
}
Streaming response event sequence:
event: response.created
event: response.in_progress
event: response.output_item.added
event: response.content_part.added
event: response.output_text.delta
event: response.output_text.done
event: response.content_part.done
event: response.output_item.done
event: response.completed
Note:
Some models, when in streaming mode, additionally output reasoning process events (response.reasoning_summary_text.delta / response.reasoning_summary_text.done).
Example: Function Calling
Function calling is a multi-round interactive process. In the first round, you define the tool and initiate the request:
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "input": "What is the weather like in Beijing today?",
    "tools": [
      {
        "type": "function",
        "name": "get_current_weather",
        "description": "Obtain the current weather for a specified location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City and province, for example: Beijing" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
          },
          "required": ["location", "unit"]
        }
      }
    ],
    "tool_choice": "auto"
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    "input": "What is the weather like in Beijing today?",
    tools=[
        {
            "type": "function",
            "name": "get_current_weather",
            "description": "Obtain the current weather for a specified location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City and province, for example: Beijing"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location", "unit"],
            },
        }
    ],
    tool_choice="auto",
)
print(response.output)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  "input": "What is the weather like in Beijing today?",
  tools: [
    {
      type: 'function',
      name: 'get_current_weather',
      "description": "Obtain the current weather for a specified location",
      parameters: {
        type: 'object',
        properties: {
          "location": { "type": "string", "description": "City and province, for example: Beijing" },
          unit: { type: 'string', enum: ['celsius', 'fahrenheit'] },
        },
        required: ['location', 'unit'],
      },
    },
  ],
  tool_choice: 'auto',
});
console.log(response.output);
import okhttp3.*;
﻿
public class FunctionCallStep1 {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "input": "What is the weather like in Beijing today?",
          "tools": [
            {
              "type": "function",
              "name": "get_current_weather",
              "description": "Obtain the current weather for a specified location",
              "parameters": {
                "type": "object",
                "properties": {
                  "location": { "type": "string", "description": "City and province, for example: Beijing" },
                  "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
                },
                "required": ["location", "unit"]
              }
            }
          ],
          "tool_choice": "auto"
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "input": "What is the weather like in Beijing today?",
  "tools": [
    {
      "type": "function",
      "name": "get_current_weather",
      "description": "Obtain the current weather for a specified location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string", "description": "City and province, for example: Beijing" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["location", "unit"]
      }
    }
  ],
  "tool_choice": "auto"
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
The first response (model calling a function) returns a function_call entry in output, and its call_id is used to submit results in the next round.
After the function result is obtained, submit it via previous_response_id + function_call_output, and the model generates the final response:
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "previous_response_id": "<id of the previous response>",
    "input": [
      {
        "type": "function_call_output",
        "call_id": "<call_id in function_call>",
        "output": "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"Sunny, light breeze\\"}"
      }
    ]
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    previous_response_id="<id of the previous response>",
    input=[
        {
            "type": "function_call_output",
            "call_id": "<call_id in function_call>",
            "output": "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"Sunny, light breeze\\"}",
        }
    ],
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  previous_response_id: '<id of the previous response>',
  input: [
    {
      type: 'function_call_output',
      call_id: '<call_id in function_call>',
      output: "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"Sunny, light breeze\\"}",
    },
  ],
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class FunctionCallStep2 {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "previous_response_id": "<id of the previous response>",
          "input": [
            {
              "type": "function_call_output",
              "call_id": "<call_id in function_call>",
              "output": "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"Sunny, light breeze\\"}"
            }
          ]
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "previous_response_id": "<id of the previous response>",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "<call_id in function_call>",
      "output": "{\\"temperature\\": 28, \\"unit\\": \\"celsius\\", \\"description\\": \\"Sunny, light breeze\\"}"
    }
  ]
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Example: Reasoning Model
cURL
Python
Node.js
Java
Go
curl https://tokenhub-intl.tencentcloudmaas.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $API_KEY" \\
  -d '{
    "model": "<your-model-name>",
    "input": "Explain the basic principles of quantum entanglement.",
    "reasoning": {
      "effort": "high"
    }
  }'
from openai import OpenAI
﻿
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://tokenhub-intl.tencentcloudmaas.com/v1")
﻿
response = client.responses.create(
    model="<your-model-name>",
    "input": "Explain the basic principles of quantum entanglement.",
    reasoning={"effort": "high"},
)
print(response.output_text)
import OpenAI from 'openai';
﻿
const client = new OpenAI({ apiKey: 'YOUR_API_KEY', baseURL: 'https://tokenhub-intl.tencentcloudmaas.com/v1' });
﻿
const response = await client.responses.create({
  model: '<your-model-name>',
  "input": "Explain the basic principles of quantum entanglement.",
  reasoning: { effort: 'high' },
});
console.log(response.output_text);
import okhttp3.*;
﻿
public class Reasoning {
    public static void main(String[] args) throws Exception {
        String body = """
        {
          "model": "<your-model-name>",
          "input": "Explain the basic principles of quantum entanglement.",
          "reasoning": {
            "effort": "high"
          }
        }
        """;
﻿
        Request request = new Request.Builder()
            .url("https://tokenhub-intl.tencentcloudmaas.com/v1/responses")
            .header("Authorization", "Bearer YOUR_API_KEY")
            .post(RequestBody.create(body, MediaType.parse("application/json")))
            .build();
﻿
        try (Response response = new OkHttpClient().newCall(request).execute()) {
            System.out.println(response.body().string());
        }
    }
}
package main
﻿
import (
    "fmt"
    "io"
    "net/http"
    "strings"
)
﻿
func main() {
    body := `{
  "model": "<your-model-name>",
  "input": "Explain the basic principles of quantum entanglement.",
  "reasoning": {
    "effort": "high"
  }
}`
﻿
    req, _ := http.NewRequest("POST",
        "https://tokenhub-intl.tencentcloudmaas.com/v1/responses",
        strings.NewReader(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
﻿
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
﻿
    data, _ := io.ReadAll(resp.Body)
    fmt.Println(string(data))
}
Filter Types
The filters field for the file search tool.
ComparisonFilter (Comparison Filter): Compares a specified attribute key with a given value.
Field
Type
Description
key
string
Key of the property to compare
type
"eq" / "ne" / "gt" / "gte" / "lt" / "lte" / "in" / "nin"
Comparison Operators
value
string / number / boolean / array
Value to compare
CompoundFilter (Compound Filter): Combines multiple filters using and or or.
Field
Type
Description
type
"and" / "or"
Operation Type
filters
array
Array of filters to be combined (ComparisonFilter or CompoundFilter)
﻿

ヘルプとサポート

この記事はお役に立ちましたか？

営業担当者にお問い合わせいただくかチケットを提出してサポートを求めることができます。

フィードバック

Field	Type	Description
`content`	string or array	Text, image, or audio input, which can also include previous assistant responses.
`role`	`"user"` / `"assistant"` / `"system"` / `"developer"`	Message role. Instructions from `developer` or `system` take precedence over those from `user`.
`phase`	`"commentary"` / `"final_answer"`	Optional. Marks an assistant message as an intermediate commentary or a final answer.
`type`	`"message"`	Optional. Message input type, always `message`.

Field	Type	Description
`detail`	`"low"` / `"high"` / `"auto"` / `"original"`	Image detail level, with `auto` as the default.
`type`	`"input_image"`	Type, always `input_image`.
`file_id`	string	Optional. File ID.
`image_url`	string	Optional. Image URL or base64-encoded data URL.

Field	Type	Description
`id`	string	The unique ID of the output message.
`type`	`"message"`	Type, always `message`.
`role`	`"assistant"`	Role, always `assistant`
`status`	`"in_progress"` / `"completed"` / `"incomplete"`	Message status.
`content`	array	An array of message content. Each item contains the `type: "output_text"` and `text` fields.

tencent cloud

LLM Service TokenHub

OpenAI Response Protocol Field Descriptions

Using the OpenAI Responses API

Request Body Parameters

Basic Parameters

Generation Control Parameters

Tool Call

Output Format Control

Inference Control

Conversation Management

Other parameters

Input Type Details

Tool Type Details

Return Value Details

Example

Example: Text Input

Example: Image Input

Example: File Input

Example: File Search

Example: Streaming Output

Example: Function Calling

Example: Reasoning Model

Filter Types

ヘルプとサポート

Parameter	Type	Required	Description
`model`	string	No	The model ID used to generate the response, such as `hy3`.
`input`	string or array	No	The text, image, or file input sent to the model. A string represents plain text (equivalent to the text of the `user` role). An array represents a list of input items. For details, see Input Type Details.
`instructions`	string	No	A system (or developer) message inserted into the model context. When the system message is used with `previous_response_id`, the instructions from the previous response do not carry over to the next response, facilitating the replacement of system messages.
`stream`	boolean	No	When set to `true`, the model response data is streamed via SSE, with events including `response.created`, `response.output_text.delta`, `response.completed`, and others.

Parameter	Type	Value Range	Description
`max_output_tokens`	number	≥ 1	The maximum number of tokens that can be generated in a response, including visible output tokens and reasoning tokens. Reasoning tokens from the reasoning model are also counted toward this limit.
`temperature`	number	[0, 2]	Sampling temperature, which controls the randomness of the output. A higher value makes the output more random and creative, while a lower value makes it more focused and deterministic.
`top_p`	number	(0, 1]	Nucleus sampling parameter. The model only considers tokens with the top `top_p` probability mass. It is recommended to adjust only one of `temperature` or `top_p`.
`truncation`	string	`"auto"` / `"disabled"`	The truncation policy when the context exceeds the model's maximum length. `auto` deletes entries from the beginning of the conversation; `disabled` (default) causes the request to fail with a 400 error when the limit is exceeded. All three models accept this parameter but do not echo it in the response body.

Value/Type	Description
`"none"`	The model does not call any tools and directly generates a message.
`"auto"`	The model can choose to generate a message or call one or more tools.
`{ "type": "function", "name": "..." }`	Forces the model to call a specific function.
`{ "type": "mcp", "server_label": "...", "name": "..." }`	Forces the model to call a tool on a specific MCP server.

Format Type	Description
`{ "type": "text" }`	The default format that generates text responses.
`{ "type": "json_schema", "name": "...", "schema": {...} }`	Structured output that ensures the model output conforms to the specified JSON Schema.
`{ "type": "json_object" }`	The legacy JSON mode that ensures the output is valid JSON (not recommended for new models).

Value	Description
`file_search_call.results`	Contains the search results from the file search tool call.
`web_search_call.results`	Contains the results from the web search tool call.
`message.input_image.image_url`	Contains the image URL from the input message.
`code_interpreter_call.outputs`	Contains the output from the code interpreter execution.
`reasoning.encrypted_content`	Contains the encrypted version of reasoning tokens, used for stateless multi-turn conversations.
`message.output_text.logprobs`	Contains the log probabilities of the assistant message.