> ## Documentation Index
> Fetch the complete documentation index at: https://docs-model.skyengine.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses API 基础调用

> 使用Responses API进行基础模型推理的示例代码

# Responses API 基础调用

Responses API 是一个统一的模型推理接口，支持多种AI模型的对话生成。本示例展示基础的文本对话调用方法。

## 快速开始

只需要替换 `<API-KEY>` 为你的实际API密钥即可运行。

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://model-api.skyengine.com.cn/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <API-KEY>" \
    -d '{
      "model": "gpt-5-2025-08-07",
      "input": [
        {
          "role": "user",
          "content": "你好，我叫张三，我今年25岁。",
          "type": "message"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  # 配置API密钥和基础URL
  API_KEY = "<API-KEY>"
  BASE_URL = "https://model-api.skyengine.com.cn/v1"

  def create_basic_response():
      """创建基础对话响应"""
      url = f"{BASE_URL}/responses"
      headers = {
          "Content-Type": "application/json",
          "Authorization": f"Bearer {API_KEY}"
      }

      payload = {
          "model": "gpt-5-2025-08-07",
          "input": [
              {
                  "role": "user",
                  "content": "你好，我叫张三，我今年25岁。",
                  "type": "message"
              }
          ]
      }

      response = requests.post(url, headers=headers, json=payload)

      if response.status_code == 200:
          result = response.json()
          
          # 从output数组中提取消息内容
          if result.get("output") and len(result["output"]) > 0:
              for output_item in result["output"]:
                  if output_item.get("type") == "message":
                      content_list = output_item.get("content", [])
                      for content in content_list:
                          if content.get("type") == "output_text":
                              print(f"AI回复: {content.get('text', '')}")

          # 显示使用统计
          usage = result.get("usage", {})
          print(f"Token使用: {usage.get('total_tokens', 0)} (输入: {usage.get('input_tokens', 0)}, 输出: {usage.get('output_tokens', 0)})")

          return result
      else:
          print(f"HTTP错误: {response.status_code}")
          print(response.text)
          return None

  # 使用示例
  if __name__ == "__main__":
      response = create_basic_response()
  ```

  ```javascript JavaScript/Node.js theme={null}
  const axios = require('axios');

  // 配置API密钥和基础URL
  const API_KEY = '<API-KEY>';
  const BASE_URL = 'https://model-api.skyengine.com.cn/v1';

  async function createBasicResponse() {
      const url = `${BASE_URL}/responses`;
      const headers = {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${API_KEY}`
      };

      const payload = {
          model: 'gpt-5-2025-08-07',
          input: [
              {
                  role: 'user',
                  content: '你好，我叫张三，我今年25岁。',
                  type: 'message'
              }
          ]
      };

      try {
          const response = await axios.post(url, payload, { headers });

          // 从output数组中提取消息内容
          if (response.data.output && response.data.output.length > 0) {
              response.data.output.forEach(outputItem => {
                  if (outputItem.type === 'message') {
                      const contentList = outputItem.content || [];
                      contentList.forEach(content => {
                          if (content.type === 'output_text') {
                              console.log(`AI回复: ${content.text}`);
                          }
                      });
                  }
              });
          }

          // 显示使用统计
          const usage = response.data.usage || {};
          console.log(`Token使用: ${usage.total_tokens || 0} (输入: ${usage.input_tokens || 0}, 输出: ${usage.output_tokens || 0})`);

          return response.data;
      } catch (error) {
          console.error('请求出错:', error.response?.data || error.message);
          return null;
      }
  }

  // 使用示例
  createBasicResponse();
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  const (
      API_KEY = "<API-KEY>"
      BASE_URL = "https://model-api.skyengine.com.cn/v1"
  )

  type InputMessage struct {
      Role    string `json:"role"`
      Content string `json:"content"`
      Type    string `json:"type"`
  }

  type ResponseRequest struct {
      Model string         `json:"model"`
      Input []InputMessage `json:"input"`
  }

  type OutputContent struct {
      Type        string   `json:"type"`
      Annotations []string `json:"annotations"`
      Logprobs    []string `json:"logprobs"`
      Text        string   `json:"text"`
  }

  type OutputMessage struct {
      ID      string          `json:"id"`
      Type    string          `json:"type"`
      Status  string          `json:"status"`
      Content []OutputContent `json:"content"`
      Role    string          `json:"role"`
  }

  type Usage struct {
      InputTokens  int `json:"input_tokens"`
      OutputTokens int `json:"output_tokens"`
      TotalTokens  int `json:"total_tokens"`
  }

  type ResponseResult struct {
      ID       string          `json:"id"`
      Object   string          `json:"object"`
      Created  int64           `json:"created_at"`
      Status   string          `json:"status"`
      Model    string          `json:"model"`
      Output   []OutputMessage `json:"output"`
      Usage    Usage           `json:"usage"`
  }

  func createBasicResponse() (*ResponseResult, error) {
      url := BASE_URL + "/responses"

      request := ResponseRequest{
          Model: "gpt-5-2025-08-07",
          Input: []InputMessage{
              {
                  Role:    "user",
                  Content: "你好，我叫张三，我今年25岁。",
                  Type:    "message",
              },
          },
      }

      jsonData, err := json.Marshal(request)
      if err != nil {
          return nil, err
      }

      httpReq, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      if err != nil {
          return nil, err
      }

      httpReq.Header.Set("Content-Type", "application/json")
      httpReq.Header.Set("Authorization", "Bearer "+API_KEY)

      client := &http.Client{}
      resp, err := client.Do(httpReq)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      var result ResponseResult
      err = json.NewDecoder(resp.Body).Decode(&result)
      if err != nil {
          return nil, err
      }

      // 从output数组中提取消息内容
      for _, output := range result.Output {
          if output.Type == "message" {
              for _, content := range output.Content {
                  if content.Type == "output_text" {
                      fmt.Printf("AI回复: %s\n", content.Text)
                  }
              }
          }
      }

      fmt.Printf("Token使用: %d (输入: %d, 输出: %d)\n",
          result.Usage.TotalTokens,
          result.Usage.InputTokens,
          result.Usage.OutputTokens)

      return &result, nil
  }

  func main() {
      response, err := createBasicResponse()
      if err != nil {
          fmt.Printf("错误: %v\n", err)
          return
      }

      fmt.Printf("响应ID: %s\n", response.ID)
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;
  import com.fasterxml.jackson.databind.ObjectMapper;
  import com.fasterxml.jackson.databind.JsonNode;

  public class ResponsesBasic {
      private static final String API_KEY = "<API-KEY>";
      private static final String BASE_URL = "https://model-api.skyengine.com.cn/v1";

      private final HttpClient client;
      private final ObjectMapper mapper;

      public ResponsesBasic() {
          this.client = HttpClient.newHttpClient();
          this.mapper = new ObjectMapper();
      }

      public JsonNode createBasicResponse() throws Exception {
          String url = BASE_URL + "/responses";

          String payload = """
              {
                  "model": "gpt-5-2025-08-07",
                  "input": [
                      {
                          "role": "user",
                          "content": "你好，我叫张三，我今年25岁。",
                          "type": "message"
                      }
                  ]
              }
              """;

          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create(url))
                  .header("Content-Type", "application/json")
                  .header("Authorization", "Bearer " + API_KEY)
                  .POST(HttpRequest.BodyPublishers.ofString(payload))
                  .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          JsonNode result = mapper.readTree(response.body());

          // 从output数组中提取消息内容
          if (result.has("output")) {
              JsonNode outputArray = result.get("output");
              for (JsonNode outputItem : outputArray) {
                  if ("message".equals(outputItem.get("type").asText())) {
                      JsonNode contentArray = outputItem.get("content");
                      for (JsonNode content : contentArray) {
                          if ("output_text".equals(content.get("type").asText())) {
                              String message = content.get("text").asText();
                              System.out.println("AI回复: " + message);
                          }
                      }
                  }
              }
          }

          if (result.has("usage")) {
              JsonNode usage = result.get("usage");
              System.out.println("Token使用: " + usage.get("total_tokens").asInt() +
                  " (输入: " + usage.get("input_tokens").asInt() +
                  ", 输出: " + usage.get("output_tokens").asInt() + ")");
          }

          return result;
      }

      public static void main(String[] args) {
          ResponsesBasic api = new ResponsesBasic();

          try {
              JsonNode response = api.createBasicResponse();
              System.out.println("响应ID: " + response.get("id").asText());
          } catch (Exception e) {
              System.out.println("执行出错: " + e.getMessage());
          }
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  class ResponsesBasic {
      private $apiKey;
      private $baseUrl;

      public function __construct($apiKey) {
          $this->apiKey = $apiKey;
          $this->baseUrl = 'https://model-api.skyengine.com.cn/v1';
      }

      public function createBasicResponse() {
          $url = $this->baseUrl . '/responses';

          $payload = [
              'model' => 'gpt-5-2025-08-07',
              'input' => [
                  [
                      'role' => 'user',
                      'content' => '你好，我叫张三，我今年25岁。',
                      'type' => 'message'
                  ]
              ]
          ];

          $headers = [
              'Content-Type: application/json',
              'Authorization: Bearer ' . $this->apiKey
          ];

          $ch = curl_init();
          curl_setopt($ch, CURLOPT_URL, $url);
          curl_setopt($ch, CURLOPT_POST, true);
          curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
          curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

          $response = curl_exec($ch);
          $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
          curl_close($ch);

          if ($httpCode === 200) {
              $result = json_decode($response, true);

              // 从output数组中提取消息内容
              if (isset($result['output'])) {
                  foreach ($result['output'] as $outputItem) {
                      if ($outputItem['type'] === 'message') {
                          foreach ($outputItem['content'] as $content) {
                              if ($content['type'] === 'output_text') {
                                  echo "AI回复: " . $content['text'] . "\n";
                              }
                          }
                      }
                  }
              }

              if (isset($result['usage'])) {
                  $usage = $result['usage'];
                  echo "Token使用: " . $usage['total_tokens'] .
                       " (输入: " . $usage['input_tokens'] .
                       ", 输出: " . $usage['output_tokens'] . ")\n";
              }

              return $result;
          } else {
              echo "HTTP错误: " . $httpCode . "\n";
              echo $response . "\n";
              return null;
          }
      }
  }

  // 使用示例
  $api = new ResponsesBasic('<API-KEY>');
  $response = $api->createBasicResponse();

  if ($response) {
      echo "响应ID: " . $response['id'] . "\n";
  }

  ?>
  ```
</CodeGroup>

## 多模态输入支持

Responses API 支持多种输入格式，包括文本、图像和文件：

### 消息列表输入

```javascript theme={null}
const response = await client.responses.create({
    model: "gpt-5-2025-08-07",
    input: [
        {
            role: "user",
            content: "你好，我叫张三，我今年25岁。",
            type: "message"
        }
    ]
});
```

### 多模态输入（文本+图像）

```javascript theme={null}
const response = await client.responses.create({
    model: "gpt-5-2025-08-07",
    input: [
        {
            role: "user",
            content: [
                {
                    type: "input_text",
                    text: "这张图片里有什么？"
                },
                {
                    type: "input_image",
                    image_url: "https://example.com/image.jpg"
                }
            ],
            type: "message"
        }
    ]
});
```

## 参数说明

### 必需参数

* `model` - 要使用的模型ID（如 gpt-5-2025-08-07, gpt-4o 等）
* `input` - 输入内容，必须是消息列表格式

### 可选参数

* `max_output_tokens` - 最大输出token数量
* `temperature` - 控制输出随机性（0-2之间）
* `stream` - 是否启用流式响应
* `tools` - 工具列表（如 web\_search, file\_search 等）

## 响应格式

成功响应包含以下字段：

```json theme={null}
{
  "id": "resp_0a7d927460af6c470068fae279feac8195a7ac939eae94a027",
  "object": "response",
  "created_at": 1761272442,
  "status": "completed",
  "background": false,
  "content_filters": null,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": 13107,
  "max_tool_calls": null,
  "model": "gpt-5-2025-08-07",
  "output": [
    {
      "id": "rs_0a7d927460af6c470068fae27a60a08195b4b87bd98c1a8e72",
      "type": "reasoning",
      "summary": []
    },
    {
      "id": "msg_0a7d927460af6c470068fae28178108195a865bc81c3fccc31",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "logprobs": [],
          "text": "张三你好，很高兴认识你！25岁正是探索和积累的好阶段。今天想聊点什么或需要我帮你做什么？"
        }
      ],
      "role": "assistant"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "medium",
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 16,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 606,
    "output_tokens_details": {
      "reasoning_tokens": 512
    },
    "total_tokens": 622
  },
  "user": null,
  "metadata": {}
}
```

## 注意事项

1. **模型选择**: 不同模型有不同的特点和成本，请根据需求选择
2. **输入格式**: 必须使用消息列表格式，每个消息包含 `role`、`content` 和 `type` 字段
3. **响应格式**: 使用 `output` 数组获取生成的内容，通过 `type` 为 `message` 的项目获取文本
4. **内容提取**: 从 `output[].content[]` 中找到 `type` 为 `output_text` 的项目获取实际文本
5. **Token统计**: 使用 `usage` 字段查看详细的token使用情况，包括推理token
6. **错误处理**: 请妥善处理API错误和异常情况
7. **速率限制**: 注意API调用频率限制

## 常见错误

* **401 Unauthorized**: 检查API密钥是否正确
* **400 Bad Request**: 检查请求参数格式和必需字段
* **429 Too Many Requests**: 降低请求频率
* **Model not found**: 检查模型名称是否正确
* **Invalid input format**: 确保输入格式符合API规范