快速接入

模型调用需要 API 基础地址、API Key 和准确的模型标识。普通 HTTP 客户端和兼容的 SDK 不需要添加 AIPUT 专用请求头。

模型调用暂未开放

下面的示例用于接入准备。调用开放后，请使用你自己的可用 Key，并将模型占位值换成模型广场中实际开放的型号。不要将示例模型或展示中的品牌视为已经可用。

准备配置

配置项	填写方式
`AIPUT_BASE_URL`	API 地址加 `/v1`；不要重复拼接 `/v1`，也不要填写首页或文档地址
`AIPUT_API_KEY`	账户下可用的 Key，放在服务端环境变量或密钥管理工具中
`AIPUT_MODEL`	模型广场列出的准确模型标识，不能用展示名称猜测

API 地址是 https://api.aiput.top，加上 /v1 就是 OpenAI 方式的基础地址 https://api.aiput.top/v1。

正式调用还需要满足账户、认证、模型范围和余额等条件。一个账户可管理多把 Key，每把 Key 归属于创建它的账户。详见账户与 API Key。

三种接口格式

同一把 Key 可以用于下面三种格式。选模型时以模型广场的标注为准：在模型广场筛选条件里的「端点类型」（窄屏时点“筛选”按钮）选择对应选项，优先使用列出的模型。格式和模型不匹配时，调用可能失败。

接口格式	请求路径	「端点类型」选项	常见用途
普通对话（OpenAI Chat Completions）	`/v1/chat/completions`	Chat	大多数 SDK 和客户端，例如 Cursor、Cline、Cherry Studio
Anthropic Messages	`/v1/messages`	Anthropic	Claude Code
OpenAI Responses	`/v1/responses`	Response	Codex

在工具里使用时，各工具要填带 /v1 还是不带 /v1 的地址不同，见工具接入。

一个文本请求

以下三种写法向 Chat Completions 端点提交同一个非流式文本请求。Python 使用标准库，Node.js 使用内置 fetch，示例不会自动重试。

cURL · 请求结构示例

export AIPUT_BASE_URL='https://api.aiput.top/v1'
export AIPUT_API_KEY='YOUR_API_KEY'
export AIPUT_MODEL='MODEL_ID_FROM_CATALOG'

curl --request POST "$AIPUT_BASE_URL/chat/completions" \
  --header "Authorization: Bearer $AIPUT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "{\"model\":\"$AIPUT_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"你好\"}],\"stream\":false}"

Python · 请求结构示例

import json
import os
import urllib.request

base_url = os.environ.get("AIPUT_BASE_URL", "https://api.aiput.top/v1")
api_key = os.environ.get("AIPUT_API_KEY", "YOUR_API_KEY")
model = os.environ.get("AIPUT_MODEL", "MODEL_ID_FROM_CATALOG")

payload = {"model": model, "messages": [{"role": "user", "content": "你好"}], "stream": False}
request = urllib.request.Request(
    base_url.rstrip("/") + "/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Authorization": "Bearer " + api_key, "Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(request, timeout=60) as response:
    print(response.read().decode("utf-8"))

Node.js · 请求结构示例

// 保存为 aiput-example.mjs，使用支持 fetch 的 Node.js 以 ES Module 运行。
const baseUrl = process.env.AIPUT_BASE_URL || 'https://api.aiput.top/v1';
const apiKey = process.env.AIPUT_API_KEY || 'YOUR_API_KEY';
const model = process.env.AIPUT_MODEL || 'MODEL_ID_FROM_CATALOG';

const response = await fetch(baseUrl.replace(/\/$/, '') + '/chat/completions', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({ model, messages: [{ role: 'user', content: '你好' }], stream: false }),
  signal: AbortSignal.timeout(60000),
});
const body = await response.text();
if (!response.ok) throw new Error('HTTP ' + response.status + ': ' + body);
console.log(body);

使用 OpenAI SDK 等客户端时，配置它提供的基础地址、API Key 和模型选项即可；不同 SDK 的参数名称可能不同。按所用版本检查超时与自动重试配置。首次接入建议关闭自动重试，避免结果不明时再次发起调用。

接口与文件限制

单次模型接口请求的完整正文上限为 64 MiB（67,108,864 字节）。文件、表单字段和 multipart 分隔内容一并计入，不能上传恰好 64 MiB 的文件再追加表单。
模型或具体端点可能要求更小的文件、更短的输入、特定格式或时长；以其接入说明为准。64 MiB 不是所有业务接口的统一额度。
兼容的端点可使用流式响应；图片、语音、视频及 WebSocket 需遵循各自模型和端点协议，不能直接套用此文本示例。当前模型调用尚未开放。
超出限制时先缩减或压缩请求，不要原样反复重试。详见常见问题中的 413 说明。

音频、文件与下载

音频接口、异步任务和文件下载以实际开放的模型与页面为准，目前尚未开放。不要将示例中的能力理解为已经可以生成或下载文件。

文件功能开放后，请按页面标示的下载有效期及时保存；不承诺永久保存生成文件。实名认证档案与生成文件采用不同的保存规则，详见隐私政策。

先核对，再重试

收到响应后，保存请求时间、模型、状态，以及响应实际提供的请求或任务编号。没有收到结果，不代表服务端没有执行。

AIPUT 不要求你自行生成请求编号，也不承诺独立请求会自动合并为一次。相同提示词或相同参数再次提交，可能产生新的调用与费用。异步任务应查询原任务，结果未知时先核对错误与恢复。

API Key 不要放进网页前端、公开仓库或截图。排查问题时只提供脱敏信息，不发送完整 Key。