更新于 2026-10-05 · 人工审核

AI API 开发者实用教程：从 Responses API 接入到 Ahri API 合规适配

本文基于 OpenAI 官方 Quickstart 资料，重构一套面向 AI API 开发者的接入流程：配置 API 密钥、使用 Responses API、处理文本、图片和文件输入，并说明如何在缺少 Ahri API 官方接口资料时，以合规、可替换的适配层方式推进接入。文中不把 OpenAI 的接口约定直接当作 Ahri API 的事实，具体端点、认证方式、模型名称和数据政策必须以 Ahri 官方文档及人工审核结果为准。

一、教程范围与资料边界

本教程面向需要在服务端调用大模型的开发者，覆盖密钥配置、官方 SDK 使用、Responses API 的基本请求结构，以及图片和文件作为输入时的代码组织方式。

已提供的唯一主要资料是 OpenAI 官方开发者 Quickstart 页面。资料展示了 OpenAI API、Responses API、JavaScript、Python、.NET、Java、Go、Ruby、curl 和 CLI 示例，也包含图片 URL、文件 URL 和上传文件作为输入的示例。

资料没有提供 Ahri API 的官方域名、API 版本、认证规范、请求路径、模型列表、SDK、配额、数据保留规则或内容安全政策。因此，本文只提供接入 Ahri API 时可复用的工程方法和适配边界，不声称 Ahri API 与 OpenAI API 兼容，也不虚构可直接运行的 Ahri 请求代码。

二、先建立服务端调用链

一个可维护的 AI API 集成通常分为四层：业务层负责组织用户任务；适配层负责屏蔽不同供应商的请求差异；传输层负责 HTTP 或 SDK 调用；治理层负责密钥、日志、权限、限流和数据处理。

业务层只表达任务，例如生成摘要、分析图片或提取文件信息。
适配层将统一的内部请求转换成供应商所需的模型、输入和选项。
传输层处理认证、超时、重试、错误映射和响应解析。
治理层限制敏感数据流向，并记录足以排障但不过度暴露内容的审计信息。

不要让业务代码直接散落供应商名称、模型名和 API Key。这样可以降低迁移成本，也便于在 Ahri API 尚未确认兼容细节时保留替换空间。

三、配置 API 密钥

OpenAI Quickstart 建议先在控制台创建 API Key，再将其放入操作系统环境变量。官方示例使用 OPENAI_API_KEY，SDK 会从环境中读取该变量。

export OPENAI_API_KEY="your_api_key_here"

Windows PowerShell 示例为：

setx OPENAI_API_KEY "your_api_key_here"

生产环境不应把密钥写入源代码、前端 JavaScript、公开仓库、镜像层或异常日志。应使用部署平台的密钥管理能力，并为不同环境和服务设置不同凭据。

Ahri API 的配置要求

在接入 Ahri API 前，应从 Ahri 官方资料确认至少以下项目：密钥申请入口、认证头名称、基础 URL、API 版本、请求路径、模型或能力标识、区域限制、速率限制、错误格式、计费规则、数据保留方式以及是否允许将特定类型的数据发送到服务端。

在这些事实完成核验前，可先定义内部配置接口，但不要把占位值发布为生产配置。

AI_PROVIDER=ahri
AHRI_API_BASE_URL=由Ahri官方文档确认
AHRI_API_KEY=通过部署环境注入
AHRI_MODEL=由Ahri官方模型目录确认

四、使用 Responses API 发起文本请求

OpenAI 资料中的基本流程是安装 SDK，创建客户端，调用 responses.create，并从 response.output_text 读取文本结果。下面保留这一流程的核心含义，但示例代码采用独立的服务函数，方便后续替换供应商。

import OpenAI from "openai";

const client = new OpenAI();

export async function generateText(prompt) {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: prompt,
  });

  return response.output_text;
}

const text = await generateText(
  "Write a one-sentence bedtime story about a unicorn."
);
console.log(text);

上述模型名称和 JavaScript SDK 调用形式来自所提供的 OpenAI 资料。模型是否可用、SDK 当前版本是否仍采用相同接口，发布前需要人工核验。

抽象成供应商无关的接口

业务代码可以只依赖一个内部函数，而不是依赖 OpenAI 或 Ahri 的具体 SDK：

export async function createAiResponse(request) {
  switch (process.env.AI_PROVIDER) {
    case "openai":
      return createOpenAiResponse(request);
    case "ahri":
      return createAhriResponse(request);
    default:
      throw new Error("Unsupported AI provider");
  }
}

createAhriResponse 不应凭猜测实现。只有在 Ahri 官方文档确认请求和响应格式后，才应填写具体的 HTTP 或 SDK 代码。

五、图片输入的请求结构

提供的 OpenAI 示例把用户输入表示为消息，消息 content 同时包含 input_text 和 input_image。图片可以通过 image_url 提供，示例还使用了 detail: auto。

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What is in this image?",
        },
        {
          type: "input_image",
          image_url: "https://example.com/image.png",
          detail: "auto",
        },
      ],
    },
  ],
});

console.log(response.output_text);

接入 Ahri API 时，需要核验其是否支持远程图片 URL、是否要求上传后返回的文件标识、支持哪些图片格式和大小、是否允许处理含个人信息的图片，以及输入图片的保存周期。不能仅因为另一家 API 支持 input_image，就推断 Ahri API 也支持同名字段。

六、文件 URL 与上传文件

资料展示了两种文件输入方式。第一种是直接把可访问的文件 URL 作为 input_file；第二种是先通过 files.create 上传本地文件，再把返回的 file.id 放入 Responses API 请求。

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI();
const file = await client.files.create({
  file: fs.createReadStream("document.pdf"),
  purpose: "user_data",
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_file",
          file_id: file.id,
        },
        {
          type: "input_text",
          text: "Summarize the key points of this document.",
        },
      ],
    },
  ],
});

console.log(response.output_text);

文件处理必须额外检查版权、授权范围、个人信息、商业秘密、恶意文件和跨境传输要求。对于来源不明的文件，应用应限制文件类型和大小，并在进入模型前执行恶意内容检测或人工审核流程。

Ahri 文件接入适配

Ahri 的文件能力需要通过官方资料确认。若 Ahri 只接受 multipart 上传，适配层就应负责上传并保存供应商文件标识；若 Ahri 接受公开 URL，则应确保 URL 的访问权限、有效期和日志脱敏；若 Ahri 不支持文件输入，则应在业务层明确返回“不支持该能力”，而不是静默改用未经授权的第三方服务。

七、错误处理与运行边界

最小可用实现不应只打印模型文本，还应处理认证失败、请求超时、参数校验失败、上游限流、服务端错误和响应结构变化。建议在适配层统一转换错误类型。

认证错误：停止重试，检查密钥、权限和环境配置。
参数错误：记录经过脱敏的参数摘要，并修正请求构造逻辑。
限流错误：遵循供应商返回的重试提示，使用有上限的退避策略。
临时服务错误：只对幂等请求进行有限次数重试。
响应解析错误：保留请求标识和供应商原始错误摘要，避免把完整敏感输入写入日志。

不要在客户端暴露供应商密钥。浏览器或移动端应调用由开发者控制的后端，由后端完成鉴权、配额控制、输入过滤和供应商路由。

八、合法合规接入 Ahri API 的检查清单

确认使用者、组织或项目拥有调用 Ahri API 所需的账户和权限。
阅读 Ahri API 的服务条款、隐私政策、数据处理协议、可接受使用政策和地区限制。
确认发送到 Ahri 的文本、图片和文件具有必要的处理授权，尤其是个人信息、医疗信息、财务信息、机密资料和受版权保护内容。
遵循最小化原则，只发送完成任务所需的数据，并在发送前移除不必要的标识信息。
通过服务端和密钥管理系统保存凭据，设置最小权限、轮换周期和撤销流程。
根据 Ahri 的要求配置保留、删除、训练使用、人工审核和跨境传输控制。
为高风险场景设置人工复核，不把模型输出直接当作法律、医疗、金融、身份认证或安全决策的唯一依据。
建立审计记录、用户告知、删除请求和安全事件响应流程。
在正式发布前用经过授权的非敏感样本进行兼容性验证，并记录模型、SDK、API 版本和测试日期。

九、适用范围与不适用范围

本文适用于搭建服务端 AI API 调用骨架、评估 Responses API 风格的文本与多模态输入、设计供应商适配层，以及规划 Ahri API 的合规接入流程。

本文不构成 Ahri API 的官方集成指南，不保证任何 Ahri 端点、字段、模型、SDK 或认证方式存在，也不替代法律意见、隐私影响评估、供应商安全审查或正式兼容性测试。

十、发布前人工核验事项

核验 OpenAI 示例中的模型名、SDK 版本、Java 依赖版本以及各语言 SDK 的当前 API 形态。
核验 OpenAI API 当前的计费、速率限制、地区可用性、数据保留和文件处理政策。
从 Ahri 官方文档确认基础 URL、版本、认证、模型、文本输入、多模态输入、文件上传、错误码和响应字段。
确认 Ahri 是否允许采用 OpenAI 兼容协议；如果不允许，应使用 Ahri 官方 SDK 或官方 HTTP 规范。
由项目的安全、隐私、法务或合规负责人确认待处理数据类别和部署区域。
在生产流量前验证超时、重试、幂等、限流、日志脱敏、密钥轮换和供应商故障切换行为。

来源

主要来源：OpenAI Developer Quickstart，https://developers.openai.com/api/docs/quickstart 。本文对 OpenAI 示例的概括、代码结构和能力范围均以用户提供的资料为基础。Ahri API 的具体事实未在资料中提供，相关内容已明确标记为待核验事项。

需要统一调用多个 AI 模型？
了解 Ahri API 中转服务

资料来源

https://developers.openai.com/api/docs/quickstart