XVAPI logoXVAPI
首页控制台模型广场API 文档关于我们博客
中文English繁體中文한국어日本語Tiếng ViệtРусский
登录
开始搭建
API 文档

开发文档

这是一套面向 XVAPI 接入的公开文档。公开契约保持简单：一个稳定 API 域名、稳定的公开模型别名，以及钱包结算。

接入摘要

Base URL
https://api.xvapi.com/v1
别名
稳定的公开名称
支持
ops@xvapi.com
最后更新
2026-09-12
版本
v2026.09.12

文档变更记录

v2026.09.12·2026-09-12

公开文档审计

  • 按当前 API 能力复核了公开接口、字段级契约和响应示例。
  • 为应用开发者明确图像选项、multipart 上传限制和重试行为。

文档总览

API 参考、接入指南与错误恢复

请按公开 `/v1` 契约接入：安全鉴权、发现可用模型、发送有效请求、处理响应，并按文档恢复可预期的失败。

阅读路径

快速开始
适合鉴权、Base URL 和第一次成功调用。
问题排查
适合状态码、频率限制、访问权限和重试决策。
图像 API
适合生成、编辑、参数选择和结果处理。

从这里开始

从需要接入的能力开始

我想完成第一次 API 调用

先确认 Base URL、Bearer 鉴权和一笔简单的文档请求。

查看快速开始↗

我需要排查调用失败

使用状态码和重试规则判断应修正请求、等待重试，还是联系支持。

查看问题排查↗

我需要图像生成或编辑

选择生成或编辑接口，校验参数，并安全处理返回的 `data` 结果。

查看图像 API↗
总览

客户最终接入到的是什么

对外 API 应该尽量简单：一套鉴权方式、一套客户钱包体系，以及稳定的公开模型别名。

稳定公开域名

保持稳定的公开接入契约，让所有客户端都能长期复用同一套对接方式。

统一鉴权标准

客户只需要一套 API Key 标准，即可调用本文列出的公开接口。

钱包结算与可追踪

每次调用都应该能回溯到请求日志、钱包预扣和最终结算记录。

快速开始

几分钟内完成第一笔成功调用

对外接入路径应该足够短：创建账号、充值余额、发放 Key、选择模型名，然后调用一个接口即可。

  1. 1创建账号并充值钱包余额。
  2. 2从平台发放对外 API Key。
  3. 3从模型列表选择稳定的公开模型名。
  4. 4调用目标接口，并确认第一笔成功返回。
第一笔成功请求
BASE_URL="https://api.xvapi.com/v1"
AUTH_HEADER="Authorization: Bearer YOUR_XVAPI_API_KEY"

curl $BASE_URL/chat/completions \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "你是一个简洁的助手。" },
      { "role": "user", "content": "打个招呼。" }
    ],
    "temperature": 0.7
  }'
SDK 示例

用官方 SDK 直接接入 XVAPI

大多数客户端不需要重写接入逻辑，只需要替换 API Key。默认建议先从 Responses API 开始，除非你必须兼容经典 chat-completions。

JavaScript / TypeScript
import OpenAI from "openai";

const BASE_URL = "https://api.xvapi.com/v1";

const client = new OpenAI({
  apiKey: "YOUR_XVAPI_API_KEY",
  baseURL: BASE_URL,
});

const response = await client.responses.create({
  model: "gpt-4.1-mini",
  input: "写一份简短的上线检查清单。"
});

console.log(response.output_text);
Python
from openai import OpenAI

BASE_URL = "https://api.xvapi.com/v1"

client = OpenAI(
    api_key="YOUR_XVAPI_API_KEY",
    base_url=BASE_URL,
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input="写一份简短的上线检查清单。"
)

print(response.output_text)
图像 API

完成第一笔图像生成请求

先调用 `/v1/models`，选择一个支持图像生成的公开模型名，再向 `/v1/images/generations` 发送一笔简单请求，并检查返回的 data 项。

你会在什么场景看到这篇

  • 你需要先完成一笔成功的图像请求，再添加高级参数。
  • 你需要确认当前 API Key 可以列出支持图像能力的模型。
  • 你需要区分普通生成请求与参考图编辑请求。

开始前先确认

把 XVAPI API Key 保存到服务端环境变量，不要写入浏览器代码。
在硬编码模型名之前，先使用该 Key 调用 `/v1/models`。
第一笔请求只生成一张图，并使用文档中列出的参数。

1. 发现图像模型

调用 `/v1/models`，选择 metadata 声明支持图像生成能力的公开模型名。

2. 发送一笔简单请求

向 `/v1/images/generations` 提交 model、prompt 和一个已支持的 size 或 quality 参数。

3. 检查响应结果

读取 data 的第一项，并按该模型返回的 URL 或 base64 载荷处理结果。

4. 逐步增加选项

基线请求成功后，再增加 n、quality、size 或参考图编辑等参数。

最常见的误区

模型列表能看到，就代表调用一定成功

不一定。模型“能列出来”和“当前调用一定成功”是两层不同检查。模型仍然可见，但当前服务配置可能已经不可用。

把 API Key 写进浏览器代码

不要把 API Key 暴露在浏览器代码或公开仓库中，应保存在应用的服务端环境变量里。

第一次就直接尝试多图生成

这会让排查变难。先把单图跑通，再去尝试多图或参考图工作流，定位会清楚得多。

下一步建议

如果校验成功但生成仍失败，下一步应该看超时与模型可用性排查，而不是继续盲试提示词。
如果你准备开始用参考图，下一步应该看编辑链说明，而不是继续反复走普通生图。
如果你不确定该公开哪些图像模型，先看模型选型说明，再决定是否暴露更多别名。
查看快速开始查看 API Key 规则查看模型
图像编辑 API

使用参考图编辑图像

编辑依赖参考文件时使用 `/v1/images/edits`；仅由文本提示词创建新图时使用 `/v1/images/generations`。

适合使用参考图的场景

你希望结果尽量贴近现有构图、主体或产品图。
你要做的是围绕一张底图的编辑和变体，而不是完全从零生成。
你想确认当前图像模型是否支持图片编辑，而不只是普通生图。

上传参考图后会发生什么

  1. 1向 `/v1/images/edits` 发送 multipart/form-data 请求。
  2. 2使用 `image` 附带参考文件，并在 `prompt` 中说明要修改的内容。
  3. 3与图像生成接口一致，读取返回的 `data` 项。

1. 先上传一张清晰参考图

第一次尽量只用一张能表达主体或构图的图片。参考图本身越杂，排查就越难。

2. 第一条编辑请求尽量简单

提示词先只写要改什么，不要第一次就同时塞太多风格、结构和细节要求。

3. 先确认模型支持 edits

有些图像模型支持普通生成，但不支持编辑。上传正常但生成失败时，要单独确认编辑能力。

4. 新图使用生成接口

不要向 `/v1/images/generations` 附带图片；该接口使用 JSON 请求体完成文生图。

常见误区

把参考图当成装饰性附件

只要参考图存在，它就会改变请求模式，不是挂在提示词旁边的静态附件。

编辑链还没稳定就直接上多图

更稳的顺序是：先单图普通生成，再单图编辑链，最后才尝试更复杂的批量流程。

参考图一直挂着，忘了为什么结果突然变了

如果结果突然开始贴着旧图片走，先看参考图缩略图是不是还在。

下一步该看什么

如果编辑请求超时，就回到超时排查那一节，把编辑链和普通生成链分开看。
如果模型能列出来但 edits 仍失败，就继续看“能看到但调用失败”那篇。
如果你想要结果更稳定，先把第一条编辑请求跑通，再去调比例和清晰度。
查看 Image Edits 接口查看 Images 接口查看超时排查
图像 API

如何选择合适的画布比例

画布比例应该服务于图片最终要去的地方，而不是凭感觉选一个最大尺寸。先选对画幅，后面的提示词调试会简单很多。

先按落地场景选比例

1:1 适合做中性方图，比如网格卡片、目录缩略图、商品方图。
4:5 或 2:3 更适合海报、文章封面和偏竖版的信息流内容。
9:16 适合手机优先、故事流或需要长竖画面的场景。
16:9 或 21:9 只在你明确需要横幅、宽景或电影感构图时再用。

实用映射

1:1

方形商品卡、通用缩略图、第一次跑 prompt 的中性测试。

4:5

社交内容、人物竖构图、市场页封面。

2:3

海报感输出、印刷比例、时尚/编辑类草稿。

9:16

手机优先页面、故事流封面、长竖场景图。

3:2 / 5:4

比电影宽幅更克制的横向构图，适合常规横图。

16:9 / 21:9

宽景、横幅、电影感画面或首页 hero 图。

先定比例，再改 prompt

如果比例和提示词复杂度一起改，你很难判断到底是什么导致了结果变化。

从最终裁切位倒推

先想清楚图片最后要放在哪个位置，再倒推画布，不要先生成一张很宽的图再硬裁成手机竖图。

只有在模型还不确定时才用自动

自动适合用来先验证链路能不能跑通，但它不能替代正式场景里的比例选择。

图像 API

清晰度选项到底影响什么

清晰度选项不是一个神奇的美化开关。它真正改变的是成本、耗时和结果稳定性之间的取舍。

标准

第一次测试 prompt、比例和模型可用性时，优先用标准。
标准通常更适合排查，因为成本更低、返回更快，也更容易看清链路本身有没有问题。
如果标准都不稳，切到高清并不能修好模型可用性问题。

高清

只有在 prompt、比例和模型都已经稳定后，再考虑切到高清。
高清通常意味着更慢的响应，在模型服务偏弱时更容易触发超时。
高清加多图，是当前最昂贵、也最容易不稳的一组组合。

先用标准排查 route

在检查超时、预算或权限问题时，不要同时把清晰度拉高，先把请求简化。

先拿到可接受结果，再升高清

当你已经得到一个可用构图时，高清才是优化步骤，而不是排错变量。

把清晰度当成工作流决策

标准适合探索，高清适合在选定模型已经可信时做最终输出。

图像结果

处理并保存返回的图像数据

成功的图像响应会在 `data` 中返回结果项。应用应校验响应、保留所需数据，并将重要资产存入自己的存储。

读取每个结果项

URL：及时读取返回的 URL；产品需要长期保留时，应存入自己的持久化存储。
Base64：按应用的二进制数据处理方式解码并保存载荷。
请求上下文：产品需要可复现能力时，保留公开模型名和提示词。
错误信息：保留状态码和请求时间，绝不保留 API Key 或 Authorization 请求头。

存储责任

将响应数据视为一次接入结果，而不是应用自己的归档存储。
需要长期保存或共享的资产，应使用自己的对象存储和访问控制。
只保留产品功能和适用隐私政策确实需要的数据。

有意识地持久化结果

在向终端用户展示前，将重要资产转存到由应用自己控制的存储中。

最小化保存可复现信息

仅在产品确有需要时保存模型别名、提示词、参数和请求时间。

结果流中不要暴露凭证

清理客户端日志和支持工单，确保 API Key 与 Authorization 请求头不会进入存储记录。

鉴权方式

所有公开接口统一使用一套 Key 标准

XVAPI API Key 只能从可信服务端环境发送，不应写入浏览器代码、移动端二进制文件或公开仓库。

Key 作用域

Key 应绑定套餐权限、钱包规则和请求日志。

请求头规则

所有公开接口都使用同一套 Bearer Key 格式，并且只应从应用的可信服务端环境发出。

API Key 管理

把客户 API Key 当成你的公开合同

应用只需要 XVAPI Key、当前套餐权限，以及该 Key 返回的公开模型列表。

  • 对外 API Key 应由你自己的平台发放，并且只应从可信服务端环境发送。
  • 必要时按套餐权限和模型白名单限制 Key 可用范围。
  • 泄露或临时使用过的 Key 应直接撤销并重新签发，不要复用旧凭证。

Key 使用方式

同一把对外 API Key 应持续用于公开模型目录、聊天、向量、图像与转写接口，不要为不同接口分发不同密钥。

Authorization: Bearer YOUR_XVAPI_API_KEY
基础约定

让对外 API 长期保持稳定

统一公开 Base URL

对外只暴露一个稳定 API 域名，让所有客户端长期复用同一套接入方式。

客户侧自有 API Key

Key 应绑定你自己的钱包、套餐权限和日志体系。

稳定的公开模型别名

保持公开模型名稳定，客户端和自动化脚本才能长期复用。

GET/v1/models

Models

返回当前调用方可访问的公开模型目录，结果会按账号套餐和 API Key 权限过滤。

公开接口

请求说明

  • 这个接口会自动过滤账号无权访问的模型、API Key 白名单外的模型和已禁用的模型。
  • 适合在客户端构建模型选择器，或在服务端缓存当前公开模型目录。
  • metadata 中会带上 billing type、展示名称等公开上下文字段。
请求示例
curl $BASE_URL/models \
  -H "$AUTH_HEADER"
响应结构
{
  "object": "list",
  "data": [
    {
      "id": "gpt-4.1-mini",
      "object": "model",
      "root": "gpt-4.1-mini",
      "metadata": {
        "label": "GPT-4.1 Mini",
        "billing_type": "token"
      }
    }
  ]
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
此接口不需要请求体。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • 返回列表已经按调用方账号和 API Key 权限过滤。
  • 图像模型可能在 metadata.image_generation 中返回支持的尺寸、清晰度和原生 4K 能力。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/chat/completions

Chat Completions

经典 OpenAI 兼容聊天入口，适合大多数现成 SDK 和已有客户端接入。

公开接口

请求说明

  • 如果你的客户端本来就是按 OpenAI chat-completions 协议写的，优先用这个。
  • 建议使用稳定的公开模型名，方便后续持续接入。
  • 每次调用都会同步记录计费和请求日志。
请求示例
{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "system", "content": "你是一个专业助手。" },
    { "role": "user", "content": "列出三项上线检查。" }
  ],
  "temperature": 0.6,
  "stream": false
}
响应结构
{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "model": "gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. 检查钱包余额..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 62,
    "total_tokens": 90
  }
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelJSON 请求体是string稳定的公开模型名。
messagesJSON 请求体是array非空消息数组，每项包含 role 和 content。
temperatureJSON 请求体否number传递给所选模型的采样参数。
max_tokensJSON 请求体否integer模型最多可生成的输出 Token 数。
streamJSON 请求体否boolean为 true 时返回 SSE 流。
reasoning_effortJSON 请求体否string支持该能力的模型可使用的推理强度提示。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-TypeJSON 请求体使用 application/json。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • 非流式响应保持 chat.completion 结构，并包含 choices 和 usage。
  • 流式响应是服务端事件，需要持续读取分片直到流关闭。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/responses

Responses

适配新版 OpenAI SDK 的统一响应接口，适合新客户端和更现代的输出结构。

公开接口

请求说明

  • 新项目如果直接用新版 SDK，可以优先采用 Responses 这一套。
  • 文本输出结构更统一，适合后续扩展更多响应能力。
  • 仍然使用同一套 API Key 和计费规则。
请求示例
{
  "model": "gpt-4.1-mini",
  "input": "写一段新模型上线说明。"
}
响应结构
{
  "id": "resp_xxx",
  "object": "response",
  "model": "gpt-4.1-mini",
  "output_text": "我们新增了一个模型...",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60
  }
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelJSON 请求体是string稳定的公开模型名。
inputJSON 请求体是string | object | array用于生成响应的输入内容。
instructionsJSON 请求体否string可选的指令文本。
max_output_tokensJSON 请求体否integer最大输出 Token 预算。
streamJSON 请求体否boolean为 true 时返回流式响应。
reasoning.effortJSON 请求体否string可选的推理强度提示。
reasoning_effortJSON 请求体否string兼容旧调用方式的 reasoning.effort 别名。
metadataJSON 请求体否object可选的调用方 metadata。
toolsJSON 请求体否array可选的工具定义，会传递给所选模型。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-TypeJSON 请求体使用 application/json。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • 公开响应使用所选模型服务返回的 Responses 兼容对象。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/embeddings

Embeddings

向量生成接口，适合语义搜索、RAG 建库、检索增强和相似度任务。

公开接口

请求说明

  • input 可以是一条文本，也可以是一组文本。
  • Embedding 计费同样会进入统一的钱包和请求记录。
  • 建议使用稳定的公开模型名称。
请求示例
{
  "model": "text-embedding-3-small",
  "input": [
    "XVAPI 网关",
    "钱包结算流程"
  ]
}
响应结构
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.074, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14
  }
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelJSON 请求体是string稳定的公开向量模型名。
inputJSON 请求体是string | string[]一条文本或多条文本。
encoding_formatJSON 请求体否string可选的向量编码格式。
dimensionsJSON 请求体否integer模型支持时可指定的输出维度。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-TypeJSON 请求体使用 application/json。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • 每个 input 对应一个 embedding 项，并返回 usage Token 统计。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/images/generations

Image Generations

图像生成接口，统一使用当前站点的模型目录、计费体系和日志体系。

公开接口

请求说明

  • 适合文本生成图片的公开接口场景。
  • 图片请求会先消耗钱包余额。
  • 建议保持公开模型名稳定，方便客户端长期使用。
请求示例
{
  "model": "gpt-image-1",
  "prompt": "一张简洁的淡蓝色科技产品插画，留有标题区域",
  "size": "1024x1024"
}
响应结构
{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/req_xxx.png"
    }
  ]
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelJSON 请求体是string公开图像模型名。
promptJSON 请求体是string用于生成图像的文本描述。
sizeJSON 请求体否string请求的画布尺寸。必须出现在所选模型的 supported_sizes metadata 中。
qualityJSON 请求体否string请求的图像质量或分辨率档位。可使用 auto、low、medium、high、1k、2k 或 4k；最终以所选模型能力为准。
nJSON 请求体否integer生成图片数量。1 到 4 的整数，默认值为 1。
response_formatJSON 请求体否string期望的图像结果编码格式。使用所选模型支持的格式；结果可能包含 URL 或 base64 载荷。
userJSON 请求体否string可选的调用方用户标识。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-TypeJSON 请求体使用 application/json。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • data 数组包含生成结果；每项可能返回 URL 或 base64，取决于所选模型和 response_format。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/images/edits

Image Edits

图片编辑接口，适合带参考图的工作流。请求包含输入图片时使用 multipart/form-data。

公开接口

请求说明

  • 当客户端上传参考图，并希望模型围绕该图片编辑或变体生成时使用这个接口。
  • 使用 multipart/form-data 提交 model、prompt 和 image 字段。
  • 编辑请求沿用图像生成同一套 API Key、模型权限、预算、钱包预扣和请求日志规则。
请求示例
curl $BASE_URL/images/edits \
  -H "$AUTH_HEADER" \
  -F model="gpt-image-1" \
  -F prompt="把这张产品图处理成干净的目录图" \
  -F image="@reference.png" \
  -F size="1024x1024"
响应结构
{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/edit_req_xxx.png"
    }
  ]
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelmultipart是string公开图像编辑模型名。
promptmultipart是string描述编辑目标的指令文本。
imagemultipart是file随请求上传的参考图。仅支持 PNG、JPEG 或 WebP；最大 8 MB；文件签名必须与 MIME 类型一致。
sizemultipart否string请求的输出尺寸。必须是所选模型支持的尺寸。
qualitymultipart否string请求的输出质量或分辨率档位。所选模型必须支持该档位。
nmultipart否integer编辑结果数量。1 到 4 的整数，默认值为 1。
response_formatmultipart否string期望的编辑图像结果编码格式。使用所选模型支持的格式。
usermultipart否string可选的调用方用户标识。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-Type使用 multipart/form-data，并让客户端自动生成 boundary。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • data 数组包含编辑结果，URL 或 base64 输出取决于所选模型。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
POST/v1/audio/transcriptions

Audio Transcriptions

音频转写接口，文件上传后按同一套鉴权、计费和日志体系处理。

公开接口

请求说明

  • 当前公开音频接口重点是转写能力。
  • 使用 multipart/form-data 提交 file 和 model 字段。
  • 请求日志和扣费会记录到同一个客户账号下。
请求示例
curl $BASE_URL/audio/transcriptions \
  -H "$AUTH_HEADER" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-mini-transcribe"
响应结构
{
  "text": "今天我们一起确认了网关发布清单..."
}

公开合同

以下字段和限制是公开接入时应依赖的边界。

字段位置必填类型说明 / 限制
modelmultipart是string公开转写模型名。
filemultipart是file需要转写的音频文件。使用所选转写模型可接受的文件格式；接入新模型时建议先用小文件验证。
languagemultipart否string可选的语言提示。
promptmultipart否string可选的上下文或词汇提示。
response_formatmultipart否string请求的转写响应格式。使用所选转写模型支持的值。
temperaturemultipart否number可选的转写采样参数。

请求头

Authorization使用 XVAPI 发放的 Bearer Token。
Content-Type使用 multipart/form-data，并让客户端自动生成 boundary。

响应说明

  • 除非接口明确说明流式或 multipart 流程，否则响应使用 JSON。
  • 规范化公开响应会在 text 字段中返回转写文本。

重试说明

  • 429 只应在退避等待后重试；如果响应包含 Retry-After，至少等待指定秒数。
  • 400、401、402、403 不要盲目重试，应先修正请求、Key、余额或访问权限。
  • 502/503 可能是临时不可用，可以使用有上限的指数退避重试，并保持同一个公开模型名。
模型字段

理解 /v1/models 返回的公开字段

公开模型目录是客户端应依赖的接入契约。使用稳定别名，并在启用模型特有的可选参数前检查 metadata。

字段类型含义
idstring客户端实际调用的公开模型名。
objectstring列表项固定为 `model`。
rootstring对外暴露的规范别名根。
metadata.labelstring用于 UI 展示的可读模型名。
metadata.billing_typestring该模型在平台上的计费方式。
模型目录

公开模型名应长期保持稳定

客户端应对接公开模型目录；在应用中启用模型前，先通过 `/v1/models` 确认该模型可访问。

客户看到的

gpt-4.1-minigpt-image-1text-embedding-3-smallgpt-4o-mini-transcribe

平台可安全调整的部分

  • 按地区和套餐控制模型可用性
  • 可用性与重试策略
  • 价格调整和套餐权限
Streaming

流式输出能力按接口区分

XVAPI 并不是每个接口都提供同样的流式能力。要把真实能力写清楚，避免客户 SDK 误判。

Responses 流式输出

如果客户端需要 SSE 输出，请在 `/v1/responses` 上使用 `stream: true`。XVAPI 会在整个流式生命周期里保持预扣、结算和请求追踪一致。

Responses 流式示例
{
  "model": "gpt-4.1-mini",
  "input": "请逐步列出上线检查项。",
  "stream": true
}

当前公开规则

Chat Completions 支持流式输出

如果客户端需要 SSE 输出，请在 `/v1/chat/completions` 上使用 `stream: true`。XVAPI 会在整个流式生命周期里保持预扣、结算和请求追踪一致。

建议规则：需要现代响应结构的客户端走 `/v1/responses`，需要保持经典 SDK 兼容的走 `/v1/chat/completions`。

计费与钱包

对外计费应以你自己的钱包系统为准

API 平台要把钱包语义做清楚：预扣、结算、释放，并让每一笔调用都能回溯到日志。

预检查

在请求开始前先验证余额和套餐权限。

预扣

必要时先创建面向客户的钱包预扣。

结算

确认用量后再写入最终结算账单。

可追踪

每一笔扣费都关联到请求日志和钱包流水。

限制与预算

每笔请求都会经过频率、套餐和预算检查

公开请求在最终结算前会受到频率限制、模型权限、套餐规则、钱包预扣和用户预算策略的约束。

频率限制

调用前先检查账号和 API Key 的频率限制。

模型权限

套餐权限和 API Key 模型白名单会共同决定可用模型。

预算策略

请求预估费用会先与用户预算策略比对，再进入预扣流程。

预扣流程

钱包与 Key 预算先预扣，待模型服务结果返回后再结算或释放。

问题排查

为什么图片生成会超时，应该先查哪里

图像生成可能比文本请求耗时更长。应按状态码处理超时和可用性错误，只重试文档明确为临时性的失败。

安全恢复顺序

  1. 1记录公开接口、模型别名、状态码和请求时间；不要记录 API Key 或 Authorization 请求头。
  2. 2遇到 429 时，如响应包含 Retry-After，应先遵守该等待时间再重试。
  3. 3遇到 502 或 503 时，使用有上限的指数退避重试；可行时让请求具备幂等性。
  4. 4遇到 400、401、402 或 403 时，应先修正请求、凭证、余额或权限，再重新发送。

何时联系支持

经过有上限的重试后，同一 5xx 响应仍持续出现。
已移除 API Key、Authorization 请求头和个人数据，但仍需要协助解释请求结果。
支持请求中应包含接口、公开模型别名、状态码和请求时间。
接入新的图像模型时，第一笔请求应只生成一张图，并使用文档支持的尺寸，再逐步增加选项。

重试必须有上限

设置较小的重试上限和指数延迟，避免临时错误造成重复计费或压垮应用自身。

不要重试客户端错误

400、401、402 和 403 应先修正再发送；重复同一请求不会解决这类问题。

构建最小复现请求

图像请求排查应先固定为一张图、一个公开别名和文档支持的参数，再逐步增加复杂度。

问题排查

为什么模型列表里能看到模型，但调用时仍然失败

模型“能看见”和模型“真能用”不是一回事。`/v1/models` 里出现模型名，只代表公开契约的一部分成立。

“能看见”通常只能证明什么

公开模型目录通过 `/v1/models` 返回了这个模型名。
公开目录里仍然暴露着这个别名。
调用方在选择器或模型列表里能看到这条模型记录。

“真能调用”还要满足什么

当前 Key 真的有权使用这个模型。
套餐规则、白名单、钱包和预算检查都允许这次调用继续执行。
公开别名仍然指向有效的模型配置。
选定的模型服务不只是出现在目录里，还能正常响应请求。

推荐排查顺序

  1. 1先确认当前 Key 通过你自己的 `/v1/models` 仍然能列出至少一个可用模型。
  2. 2检查失败模型是否被套餐规则、白名单或钱包 / 预算策略拦住。
  3. 3确认公开别名当前仍然指向预期模型，而不是陈旧配置。
  4. 4如果模型能看见但仍然失败，先用一条简单的正常请求验证，再尝试更复杂的参数。
错误码

错误信息要让支持团队能直接处理

状态码含义说明
400请求体格式错误、字段缺失、JSON 非法，或参数组合不受支持。
401API Key 缺失或无效，先检查 Bearer Token。
402钱包余额不足，或当前计费规则拒绝了这次请求。
403当前账号、套餐或模型权限不允许这次调用。
429当前账号或 API Key 命中了频率/并发限制。
500服务暂时异常，请记录请求时间和模型；若持续发生请联系支持。
502/503请求的能力暂时不可用，请稍后使用有上限的指数退避重试。
400 · 缺少必要字段
{
  "error": {
    "message": "model and messages are required"
  }
}
401 · API Key 无效
{
  "error": {
    "message": "Invalid API key"
  }
}
402

余额不足

{
  "error": {
    "message": "Insufficient wallet balance"
  }
}
429

命中频率限制

{
  "error": {
    "message": "Rate limit exceeded"
  }
}
403

模型权限不足

{
  "error": {
    "message": "Model not allowed for current package"
  }
}
503

图像生成暂时不可用

{
  "error": {
    "message": "Image generation is temporarily unavailable. Please retry or choose another model."
  }
}

重试策略

按错误类别处理

不能只看状态码决定是否重试，应先按错误类别执行对应处理。

400不要重试

请求校验错误

请求体格式错误、缺少必填字段，或使用了当前模型不支持的参数。

处理： 先修正请求结构或参数，再重新发送。

401/402/403不要重试

鉴权、余额或访问权限

Key、钱包、套餐、预算策略或模型权限阻止了本次请求。

处理： 先修正凭证、余额、套餐、预算或模型权限。

429退避后重试

频率或并发限制

当前账号或 API Key 达到了请求限制，平台可能返回 Retry-After。

处理： 等待并遵守 Retry-After，再使用有上限的退避策略重试。

500视情况重试

服务异常

平台完成常规检查后仍无法完成本次请求。

处理： 不要高频循环重试，应结合请求时间、模型和支持日志排查。

502/503视情况重试

模型服务临时不可用

所选模型服务可能暂时不可用、性能下降或超时。

处理： 使用有上限的指数退避重试，并保持同一个公开模型名。

FAQ 与支持

很多支持问题最终都和计费、限制或模型权限有关

应用应该调用哪个 API 域名？

使用本文给出的公开 Base URL，并搭配 XVAPI 账号签发的 API Key。

定价应该怎么对外说明？

从用户视角清楚说明钱包余额、模型单价和结算规则即可。

请求看起来异常时，支持团队先看什么？

先看请求日志、钱包流水、模型名、请求时间，以及到底是计费问题还是单纯延迟问题。

服务调整时，公开模型名还能保持稳定吗？

不应该。只要公开模型名保持稳定，客户端就不需要修改接入。