接入参考Developer Guide
从创建密钥到发起第一条请求。以下示例使用兼容 OpenAI 的接口;实际可用模型与能力请以实时模型列表为准。From creating an API key to your first request. The examples below use an OpenAI-compatible API; the models and capabilities actually available are subject to the live model list.
快速开始Quick Start
在模型广场确认模型 ID、价格与支持的接口。Confirm the model ID, pricing and supported endpoints in the model marketplace.
登录后在 API 密钥页创建密钥,并保存在服务端。After signing in, create a key on the API Keys page and keep it on your server.
将基础地址和密钥填入现有 OpenAI 兼容客户端。Point your existing OpenAI-compatible client at the base URL with the key.
基础地址与鉴权Base URL & Authentication
| API 基础地址Base URL | https://api.sxwanwu.cn/v1 |
|---|---|
| 鉴权方式Authentication | Authorization: Bearer YOUR_API_KEY |
| 请求格式Request format | JSON 请求使用 Content-Type: application/jsonJSON requests use Content-Type: application/json |
| 密钥入口Key console | 控制台 · API 密钥Console · API Keys |
示例中的 YOUR_API_KEY 是占位符。请在自己的服务端使用环境变量保存真实密钥,避免放入网页、客户端安装包或公开仓库。YOUR_API_KEY in the examples above is a placeholder. Store real keys in server-side environment variables only — never in web pages, client bundles or public repositories.
获取模型列表List Models
调用 GET /v1/models 获取当前密钥可使用的模型 ID。模型会动态变化,接入时不要把列表写死。Call GET /v1/models to list the model IDs your key can use. Models change over time — never hard-code the list.
curl https://api.sxwanwu.cn/v1/models \
-H "Authorization: Bearer $XSW_API_KEY"先在终端设置 XSW_API_KEY 环境变量。返回结果中的 data[].id 是请求使用的模型 ID;supported_endpoint_types 可用于判断接口类型。Set the XSW_API_KEY environment variable in your shell first. In the response, data[].id is the model ID used in requests, and supported_endpoint_types tells you which endpoints the model supports.
对话请求Chat Completions
文字模型使用 POST /v1/chat/completions。下面的模型 ID 只是当前示例,正式接入前请查询模型列表。Text models use POST /v1/chat/completions. The model ID below is only an example — always query the model list before going live.
curl https://api.sxwanwu.cn/v1/chat/completions \
-H "Authorization: Bearer $XSW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "你好,请用一句话介绍你自己"}]
}'常见响应位于 choices[0].message.content。不同模型对参数的支持可能不同,首次接入先用最小请求验证。The reply is usually at choices[0].message.content. Parameter support varies by model — validate with a minimal request first.
流式输出Streaming
对话请求加入 "stream": true,服务端会按 SSE 事件逐段返回。客户端需持续读取响应流,直到收到结束标记。Add "stream": true to a chat request and the server returns SSE events incrementally. Keep reading the stream until the terminating marker arrives.
curl -N https://api.sxwanwu.cn/v1/chat/completions \
-H "Authorization: Bearer $XSW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "用三句话介绍春天"}],
"stream": true
}'图像生成Image Generation
支持图像生成的模型使用 POST /v1/images/generations。先在模型列表确认该模型的 supported_endpoint_types 包含 image-generation,并查看其当前状态。Image-capable models use POST /v1/images/generations. First confirm the model's supported_endpoint_types includes image-generation, and check its current status.
curl https://api.sxwanwu.cn/v1/images/generations \
-H "Authorization: Bearer $XSW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "你的图像模型ID",
"prompt": "一只坐在窗边的橘猫,柔和自然光",
"size": "1024x1024"
}'图像请求通常比文字请求更久。返回内容的形式依模型而异,可能是图片地址或编码数据;请根据实际响应处理。Image requests usually take longer than text requests. The response shape varies by model — it may be an image URL or encoded data; handle it according to the actual response.
Python SDKPython SDK
已有 OpenAI Python SDK 项目可设置自定义 base_url,并从环境变量读取密钥。An existing OpenAI Python SDK project just needs a custom base_url, reading the key from an environment variable.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["XSW_API_KEY"],
base_url="https://api.sxwanwu.cn/v1",
)
response = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)安装 SDK:pip install openai。如模型有专属参数要求,请按模型详情调整。Install the SDK with pip install openai. If a model requires specific parameters, follow its model details.
错误处理Error Handling
| 状态码Status | 常见原因Common cause | 建议处理Suggested action |
|---|---|---|
401 | 密钥缺失、错误或失效Missing, wrong or revoked key | 检查 Bearer 头和密钥状态。Check the Bearer header and key status. |
403 | 权限或模型访问受限Permission or model access denied | 检查密钥分组、模型权限和账户状态。Check key group, model permissions and account status. |
429 | 请求频率或额度达到限制Rate limit or quota reached | 降低并发,按响应提示稍后重试。Reduce concurrency and retry later as indicated. |
5xx | 网关或上游暂时异常Temporary gateway or upstream error | 查看模型状态,有限次数重试并记录错误响应。Check model status, retry a limited number of times and log the response. |
不要对所有错误无限重试;先记录状态码和响应内容,便于定位。Never retry every error indefinitely; log the status code and response body first so the issue can be diagnosed.
安全与排查Security & Troubleshooting
- 真实密钥仅保存在服务端环境变量或密钥管理服务中;不要写入前端代码和日志。Keep real keys only in server-side environment variables or a secrets manager; never in front-end code or logs.
- 发起调用前,确认模型 ID 来自当前密钥可访问的模型列表。Before calling, make sure the model ID comes from the list your key can access.
- 用使用日志核对请求记录,用模型状态判断是否有持续异常。Use Usage Logs to verify requests and Model Status to spot persistent issues.
- 状态页每小时抽样一次;一次绿色记录不代表所有请求都必然成功。The status page samples every hour; a single green record does not guarantee that every request succeeds.
