# see2ai_llm_gpt_5_4_v1

> GPT-5.4 高级版多模态 AI 对话服务，支持文本对话、图片理解、文件分析（PDF等）、联网搜索及深度推理模式。适用于需要更高智能水平的场景。

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_llm_gpt_5_4_v1`

**认证方式**: Bearer Token (租户 API Key)

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台封装后的接口，**参数格式与上游官方（如火山引擎、OpenAI等）API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考官方文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "description": "GPT-5.4 高级版对话输入模型",
  "properties": {
    "query": {
      "description": "用户问题内容",
      "title": "Query",
      "type": "string"
    },
    "image_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": [],
      "description": "图片 URL 列表（可选），支持多张图片理解。注意：只接受公网 URL。如果当前只有本地文件，请先调用 `see2ai_storage_upload_v1` 上传并获取 URL。",
      "title": "Image Urls"
    },
    "file_urls": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": [],
      "description": "文件 URL 列表（可选），支持 PDF 等文档分析。注意：只接受公网 URL。如果当前只有本地文件，请先调用 `see2ai_storage_upload_v1` 上传并获取 URL。",
      "title": "File Urls"
    },
    "enable_web_search": {
      "default": false,
      "description": "是否启用联网搜索获取实时信息",
      "title": "Enable Web Search",
      "type": "boolean"
    },
    "reasoning_effort": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "推理深度控制（可选）：none / minimal / low / medium / high / xhigh。设置后会启用深度推理模式，消耗更多 token 但推理更深入。",
      "title": "Reasoning Effort"
    },
    "temperature": {
      "default": 0.7,
      "description": "温度参数，控制随机性",
      "maximum": 2.0,
      "minimum": 0.0,
      "title": "Temperature",
      "type": "number"
    },
    "stream": {
      "default": false,
      "description": "是否启用流式返回",
      "title": "Stream",
      "type": "boolean"
    },
    "max_output_tokens": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "最大输出 token 数限制",
      "title": "Max Output Tokens"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "支持的工具列表，用于函数调用",
      "title": "Tools"
    },
    "tool_choice": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "工具调用选项，例如 'auto' 或指定某个工具",
      "title": "Tool Choice"
    }
  },
  "required": [
    "query"
  ],
  "title": "GPT54ChatInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `query` | string | ✅ 是 | `-` | 用户问题内容 |
| `image_urls` | string | ❌ 否 | `[]` | 图片 URL 列表（可选），支持多张图片理解。注意：只接受公网 URL。如果当前只有本地文件，请先调用 `see2ai_storage_upload_v1` 上传并获取 URL。 |
| `file_urls` | string | ❌ 否 | `[]` | 文件 URL 列表（可选），支持 PDF 等文档分析。注意：只接受公网 URL。如果当前只有本地文件，请先调用 `see2ai_storage_upload_v1` 上传并获取 URL。 |
| `enable_web_search` | boolean | ❌ 否 | `False` | 是否启用联网搜索获取实时信息 |
| `reasoning_effort` | string | ❌ 否 | `-` | 推理深度控制（可选）：none / minimal / low / medium / high / xhigh。设置后会启用深度推理模式，消耗更多 token 但推理更深入。 |
| `temperature` | number | ❌ 否 | `0.7` | 温度参数，控制随机性 |
| `stream` | boolean | ❌ 否 | `False` | 是否启用流式返回 |
| `max_output_tokens` | string | ❌ 否 | `-` | 最大输出 token 数限制 |
| `tools` | string | ❌ 否 | `-` | 支持的工具列表，用于函数调用 |
| `tool_choice` | string | ❌ 否 | `-` | 工具调用选项，例如 'auto' 或指定某个工具 |

## 📤 输出结果 (Output Schema)

```json
{
  "$defs": {
    "GPT54UsageMetadata": {
      "description": "词元使用统计",
      "properties": {
        "input_tokens": {
          "default": 0,
          "title": "Input Tokens",
          "type": "integer"
        },
        "output_tokens": {
          "default": 0,
          "title": "Output Tokens",
          "type": "integer"
        },
        "total_tokens": {
          "default": 0,
          "title": "Total Tokens",
          "type": "integer"
        }
      },
      "title": "GPT54UsageMetadata",
      "type": "object"
    }
  },
  "description": "GPT-5.4 高级版对话输出模型",
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入词元",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出词元",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总词元",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "default": "",
      "description": "实际使用的模型名称（由各 action 显式填写）",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "default": "gptproto",
      "description": "模型来源",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "response": {
      "description": "GPT-5.4 的回答",
      "title": "Response",
      "type": "string"
    },
    "thinking_content": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "推理过程内容（如果启用了 reasoning_effort）",
      "title": "Thinking Content"
    },
    "tool_calls": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "模型要求调用的工具列表",
      "title": "Tool Calls"
    },
    "usage": {
      "anyOf": [
        {
          "$ref": "#/$defs/GPT54UsageMetadata"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "API 使用量统计"
    },
    "provider_config_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "供应商配置 ID（用于追溯）",
      "title": "Provider Config Id"
    }
  },
  "required": [
    "response"
  ],
  "title": "GPT54ChatOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入词元 |
| `output_tokens` | integer | 输出词元 |
| `total_tokens` | integer | 总词元 |
| `model` | string | 实际使用的模型名称（由各 action 显式填写） |
| `source` | string | 模型来源 |
| `cost_points` | string | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `response` | string | GPT-5.4 的回答 |
| `thinking_content` | string | 推理过程内容（如果启用了 reasoning_effort） |
| `tool_calls` | string | 模型要求调用的工具列表 |
| `usage` | string | API 使用量统计 |
| `provider_config_id` | string | 供应商配置 ID（用于追溯） |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_llm_gpt_5_4_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "query": "请解释量子纠缠的原理",
  "image_urls": "https://example.com/image.jpg",
  "file_urls": "https://example.com/image.jpg",
  "enable_web_search": true,
  "reasoning_effort": "示例值",
  "temperature": 0.7,
  "stream": false,
  "max_output_tokens": "示例值",
  "tools": "示例值",
  "tool_choice": "示例值"
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_llm_gpt_5_4_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "query": "\u8bf7\u89e3\u91ca\u91cf\u5b50\u7ea0\u7f20\u7684\u539f\u7406",
  "image_urls": "https://example.com/image.jpg",
  "file_urls": "https://example.com/image.jpg",
  "enable_web_search": true,
  "reasoning_effort": "\u793a\u4f8b\u503c",
  "temperature": 0.7,
  "stream": false,
  "max_output_tokens": "\u793a\u4f8b\u503c",
  "tools": "\u793a\u4f8b\u503c",
  "tool_choice": "\u793a\u4f8b\u503c"
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> 按输入/输出词元计费，图片和文件将根据 GPTProto 官方规则转换为相应词元，深度推理模式（reasoning_effort）产生的推理词元也会计入总消耗。

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `401` | API Key 无效或租户余额不足 | 检查 API Key 是否正确，或联系管理员充值 |
| `403` | 权限不足或供应商余额不足 | 请稍后重试 |
| `422` | 输入参数格式错误（如非法的 URL 或不支持的 reasoning_effort 值） | 检查请求参数是否符合 Schema 要求 |
| `429` | 调用频率超限 (Rate Limit Exceeded) | 降低请求频率，或联系管理员调整限流配置 |
| `502` | GPTProto 上游响应异常 | 请稍后重试 |
| `504` | GPTProto 上游响应超时 | 请稍后重试 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_llm_gpt_5_4_v1
**最后更新**: 2026-03-23