WisGate API 基础文档

本文档说明 WisGate API 的通用调用方式。图片、视频等模型系列文档会复用这里的 Base URL、鉴权、错误响应、异步任务轮询和安全约定。

基础信息

项目	说明
Base URL	https://api.wisgate.cn
OpenAI 兼容 Base URL	https://api.wisgate.cn/v1
鉴权方式	Authorization: Bearer YOUR_API_KEY
JSON 请求格式	Content-Type: application/json
表单请求格式	multipart/form-data，通常用于图像编辑上传图片

不要在代码仓库、文档、日志或截图中暴露真实 API Key。本文档中的 YOUR_API_KEY 仅为占位符。

API Key

调用 WisGate API 时，请在服务端保存 API Key，并通过 Authorization 请求头发送：

Authorization: Bearer YOUR_API_KEY

推荐做法：

• 为不同业务、环境或客户创建独立 API Key，便于限流、审计和停用。
• 不要把 API Key 放到浏览器端、移动端包体、公开 Git 仓库或前端环境变量中。
• 生产环境建议记录请求 ID、任务 ID、模型名、状态和耗时，避免记录完整密钥。
• 出现密钥泄露风险时，应立即停用旧密钥并替换为新密钥。

常用入口

能力	方法	路径
对话补全	POST	/v1/chat/completions
Responses	POST	/v1/responses
图片生成	POST	/v1/images/generations
图片编辑	POST	/v1/images/edits
Seedance 视频任务	POST	/api/v3/contents/generations/tasks
Seedance 视频查询	GET	/api/v3/contents/generations/tasks/{id}
Seedance 资产创建	POST	/api/v3/open/CreateAsset
火山 Seedream 原生图片生成	POST	/api/v3/images/generations

Base URL 不带 /v1 的场景请使用 https://api.wisgate.cn。OpenAI SDK 或 OpenAI 兼容接口的 base_url / baseURL 请使用 https://api.wisgate.cn/v1。

鉴权示例

curl https://api.wisgate.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-r1",
    "messages": [
      {
        "role": "user",
        "content": "你好"
      }
    ]
  }'

OpenAI SDK 示例

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.wisgate.cn/v1",
)

response = client.chat.completions.create(
    model="deepseek-r1",
    messages=[
        {"role": "user", "content": "你好"}
    ],
)

print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.wisgate.cn/v1",
});

const response = await client.chat.completions.create({
  model: "deepseek-r1",
  messages: [
    { role: "user", content: "你好" },
  ],
});

console.log(response.choices[0]?.message?.content);

错误响应

错误响应通常遵循 OpenAI 兼容结构；不同上游渠道的原始错误可能会被归一化到 error.message、error.type 和 error.code 中：

{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

字段	说明
error.message	可读错误信息
error.type	错误类型，例如 invalid_request_error
error.code	错误码，便于业务侧分支处理

常见处理建议：

场景	处理建议
401 或鉴权失败	检查 API Key 是否正确、是否仍有效、请求头是否为 Authorization: Bearer YOUR_API_KEY
model is required	检查 JSON 请求体或 multipart 表单是否包含 model
参数格式错误	对照对应系列文档确认字段名、类型和尺寸格式
上游任务超时	异步图片、视频任务可能需要更长时间；客户端请求超时建议按业务场景放宽
结果 URL 过期	生成图片、视频 URL 通常有有效期，业务侧应及时下载或转存

异步任务轮询

Seedance 生视频等能力会先创建任务，再通过任务 ID 查询结果。

1. 创建任务接口返回 id。
2. 客户端保存 id，稍后请求查询接口。
3. 当状态进入 succeeded、failed、expired、cancelled 等终态后停止轮询。
4. 生成结果 URL 通常有有效期，建议业务侧及时下载或转存。

建议首次查询从任务提交后数分钟开始；如果业务需要更快反馈，可逐步缩短查询间隔，但应避免高频无意义轮询。视频生成、图像异步任务和上游排队时间会随模型、分辨率、时长和素材复杂度变化。

回调安全

部分异步任务支持 callback_url。回调内容与查询结果结构一致，调用方应按以下方式处理：

• 回调地址必须是服务端 HTTPS 地址，不建议使用本地地址或临时公网代理。
• 回调处理逻辑应具备幂等能力，同一个任务状态可能被重复投递。
• 收到回调后仍建议按任务 ID 查询一次结果，作为最终状态确认。
• 不要在回调 URL 中拼接 API Key、用户密钥或敏感业务参数。

文件 URL 与素材要求

图片编辑、Seedance 资产和视频参考素材通常需要传入图片、视频或音频 URL：

• URL 应可被上游服务公网访问，避免需要登录、内网访问或临时 Cookie 的地址。
• 如果素材 URL 有有效期，请确保有效期覆盖任务排队和生成时间。
• Base64 输入适合小文件或短素材；大文件建议使用公网 URL 或先创建资产。
• 如需多次复用素材，Seedance 建议先创建资产，再使用 asset://ASSET_ID 引用。

安全建议

• 服务端保存 API Key，不要把密钥放到浏览器、移动端包体或公开仓库。
• 为终端用户生成不可逆的 safety_identifier，避免直接传手机号、邮箱等敏感信息。
• 对上传或引用的图片、视频、音频 URL 做来源校验，确保素材可被上游访问。
• 生产环境建议记录 RequestId、任务 ID、模型名和状态，避免记录完整提示词或密钥。
• 生成结果 URL 如需长期保存，应由业务侧转存到自己的对象存储。