03. 广泛设备的接入与调优指南

无论您是单纯想尝试 AI 对话的用户，还是进行严肃开发的工程师，SiliEvo 都提供了完美的"热插拔"适配体验。

前提条件：
请牢记 SiliEvo 中转服务的核心两要素，缺一不可：

中转基地址 (Base URL): https://api.numspirit.com/v1 （切勿遗漏 /v1）

安全秘钥 (API Key / Token): 通过平台官网 https://numspirit.com 或联系 15685255305 申请，形如 sk-silievo-xxxxxxxx。

🛠️ 第一部分：开发者快速连通测试

方法 1：使用 Postman

若需要抓包或详尽测试网络响应时间：

Method: POST

URL: https://api.numspirit.com/v1/chat/completions

Headers 头部:

Content-Type: application/json
Authorization: Bearer sk-silievo-xxxxxxxx (在这里换成你的Key，注意 Bearer 后带空格)

Body 内容 (raw + JSON):

{
    "model": "qwen3.6-plus",
    "messages": [
        { "role": "system", "content": "你是一位优秀的向导。" },
        { "role": "user", "content": "跟我打个招呼！" }
    ],
    "stream": false
}

点击 Send 后，您会在下方窗口收到带有 choices 的 JSON 格式的回复大包。

方法 2：使用 cURL 命令行终端

打开 Mac Terminal 或 Windows PowerShell/CMD 进行一键测试：

🖼️ 第二部分：图片生成接口（文生图/图生图）

SiliEvo 平台支持图片生成能力，接口采用 OpenAI 兼容格式。

2.1 接口概览

功能	接口路径	方法	说明
图片生成	`/v1/images/generations`	POST	文生图、图生图

2.2 文生图

接口: POST https://api.numspirit.com/v1/images/generations

请求参数:

{
  "model": "wan2.7-image",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "text": "一只可爱的小狗在阳光下奔跑"
          }
        ]
      }
    ]
  },
  "parameters": {
    "size": "1024*1024",    // 可选：图片尺寸，如 1024*1024、1024*768、768*1024 等
    "n": 1                  // 可选：生成数量，默认 1
  }
}

响应示例（成功）:

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "content": [
            {
              "image": "https://dashscope-7c2c.oss-accelerate.aliyuncs.com/xxx/xxx.png",
              "type": "image"
            }
          ],
          "role": "assistant"
        }
      }
    ],
    "finished": true
  },
  "usage": {
    "image_count": 1,
    "input_tokens": 27,
    "output_tokens": 2,
    "total_tokens": 29
  },
  "request_id": "ad94fd27-84c2-9777-9641-a62e49212d43"
}

cURL 示例 - 文生图:

cURL 示例 - 图生图:

待补充

🎬 第三部分：视频生成接口（文生视频/图生视频）

视频生成采用异步任务模式：提交任务 → 获取 task_id → 轮询查询状态 → 获取结果。

重要说明：视频生成请求需要在 HTTP Header 中添加 X-DashScope-Async: enable 字段以启用异步模式。

3.1 接口概览

功能	接口路径	方法	说明
视频生成	`/v1/videos/generations`	POST	文生视频、图生视频（需异步Header）
视频任务查询	`/v1/videos/generations/{task_id}`	GET	查询异步生成任务状态

3.2 文生视频

接口: POST https://api.numspirit.com/v1/videos/generations

请求 Header:

Content-Type: application/json
Authorization: Bearer sk-silievo-xxxxxxxx
X-DashScope-Async: enable    // 必须：启用异步模式

请求参数:

{
  "model": "happyhorse-1.0-t2v",      // 必填：文生视频模型ID
  "prompt": "一座未来城市，飞行汽车在空中穿梭",  // 必填：视频描述
  "resolution": "720P",               // 可选：分辨率，默认 720P，可选值：720P、1080P
  "aspect": "16:9",                   // 可选：视频比例，默认 16:9，可选值：16:9、9:16、1:1
  "duration": 5                       // 可选：视频时长（秒），默认 5 秒
}

cURL 示例 - 文生视频:

响应示例（提交成功）:

{
  "success": true,
  "data": {
    "task_id": "9dc4e5f1-69b5-4874-b475-f815b8a30a5d",
    "model": "happyhorse-1.0-t2v",
    "status": "PENDING"
  }
}

3.3 视频任务状态查询

接口: GET https://api.numspirit.com/v1/videos/generations/{task_id}?model={model_id}

重要: 查询时必须带上 model 参数，用于确定查询的渠道。

请求示例:

响应示例（进行中）:

{
  "success": true,
  "data": {
    "task_id": "9dc4e5f1-69b5-4874-b475-f815b8a30a5d",
    "status": "running",
    "output_urls": [],
    "error": null
  }
}

响应示例（成功）:

{
  "success": true,
  "data": {
    "task_id": "9dc4e5f1-69b5-4874-b475-f815b8a30a5d",
    "status": "succeeded",
    "output_urls": [
      "https://dashscope-a717.oss-accelerate.aliyuncs.com/1d/ef/20260524/xxx/xxx.mp4"
    ],
    "error": null
  }
}

3.4 图生视频

待补充

3.5 支持的视频模型

模型ID	描述	支持功能
`happyhorse-1.0-t2v`	文生视频模型	文生视频
`happyhorse-1.0-i2v`	图生视频模型	图生视频

3.6 完整的视频生成工作流示例（Python）

💻 第四部分：主流编程语言代码挂载

-d '{
"model": "wan2.7-image-pro",
"prompt": "将图片转换成动漫风格",
"images": ["https://example.com/original.jpg"],
"aspect": "16:9"
}'


### 2.3 图片任务状态查询

**接口**: `GET https://api.numspirit.com/v1/images/generations/{task_id}?model={model_id}`

**请求示例**:
```bash
curl https://api.numspirit.com/v1/images/generations/task-20260524-xxxxxxxx?model=wan2.7-image \
  -H "Authorization: Bearer sk-silievo-xxxxxxxx"

响应示例:

{
  "success": true,
  "data": {
    "task_id": "task-20260524-xxxxxxxx",
    "status": "succeeded",
    "output_urls": [
      "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx/xxx.png"
    ],
    "error": null
  }
}

状态说明:

PENDING: 任务排队中

RUNNING: 正在生成

succeeded: 生成完成

failed: 生成失败

2.4 文生视频 / 图生视频

接口: POST https://api.numspirit.com/v1/videos/generations

请求参数:

{
  "model": "wan2.1-t2v",             // 必填：模型ID，如 wan2.1-t2v（文生视频）、wan2.1-i2v（图生视频）
  "prompt": "一片樱花飘落的街道",     // 必填：视频描述
  "aspect": "16:9",                  // 可选：视频比例，默认 16:9，可选值：16:9、9:16、1:1
  "resolution": "720P",              // 可选：分辨率，默认 720P，可选值：720P、1080P
  "duration": 5,                     // 可选：视频时长（秒），默认 5 秒
  "images": []                       // 可选：图生视频时的参考图片 URL 数组（最多 1 张）
}

cURL 示例 - 文生视频:

cURL 示例 - 图生视频:

2.5 视频任务状态查询

接口: GET https://api.numspirit.com/v1/videos/generations/{task_id}?model={model_id}

请求示例:

响应示例（成功）:

{
  "success": true,
  "data": {
    "task_id": "task-20260524-xxxxxxxx",
    "status": "succeeded",
    "output_urls": [
      "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx/xxx.mp4"
    ],
    "error": null
  }
}

2.6 支持的模型列表

图片生成模型:

模型ID	描述	支持功能
`wan2.7-image`	通义万相 2.7 基础版	文生图、图生图
`wan2.7-image-pro`	通义万相 2.7 专业版	文生图、图生图
`qwen-image-2.0`	通义千问生图模型	文生图
`qwen-image-2.0-pro`	通义千问生图模型专业版	文生图

视频生成模型:

模型ID	描述	支持功能
`wan2.1-t2v`	通义万相 2.1 文生视频	文生视频
`wan2.1-i2v`	通义万相 2.1 图生视频	图生视频

2.7 完整的图片生成工作流示例（Python）

💻 第三部分：主流编程语言代码挂载

我们对 OpenAI 官方 SDK 做到了零代码修改级兼容，您只需将其重定向到 SiliEvo：

Python (推荐使用官方 `openai` 包)

Node.js / TypeScript

🦞 第六部分：高级场景 - 接入龙虾 (Lobster / OpenClaw) Agent 构架

龙虾是强大的 Multi-Agent 开发框架。在其 JSON 配置文件中，您可以极速将底层心智引擎替换为我们要提供的丰富模型矩阵。

片段 1: 初始化大模型提供商 (Providers)

在配置文件全局部分声明 Provider 节点：

"custom-coding-dashscope-aliyuncs-com": {
  "baseUrl": "https://api.numspirit.com/v1",
  "apiKey": "sk-silievo-xxxxxxxxxxxxxxxxxx",  
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen3.6-plus",
      "name": "qwen3.6-plus (Custom Provider)",
      "reasoning": false,
      "input": ["text"],
      "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
      "contextWindow": 262144,
      "maxTokens": 8192,
      "compat": { "supportsStrictMode": true }
    }
  ]
}

片段 2: 全局 Agents 的模型路由规划 (Defaults)

在 agents -> defaults 下指派您的偏好机制，这样框架崩溃率会大幅降低：

"agents": {
  "defaults": {
    "model": {
      "primary": "custom-coding-dashscope-aliyuncs-com/qwen3.6-plus",
      "fallbacks": [
        "custom-coding-dashscope-aliyuncs-com/qwen3.6-plus",
        "nvidia/minimaxai/minimax-m2.5",
        "openrouter/auto",
        "openai/gpt-5.4",
        "anthropic/claude-sonnet-4-5",
        "deepseek/deepseek-reasoner",
        "opencode/qwen3.6-plus-free"
      ]
    },
    // 将图像模型单独指派，若需要的话
    "imageModel": {
      "primary": "custom-coding-dashscope-aliyuncs-com/qwen3.6-plus"
    },
    "compaction": {
      "mode": "safeguard",
      "reserveTokens": 8000,
      "keepRecentTokens": 12000,
      "maxHistoryShare": 0.6,
      // 这是指导大模型如何与底层打交道的关键指令
      "identifierInstructions": "每次调用 read/write/edit 工具必须包含 path 参数，严禁发送空参数。"
    }
  }
}

通过以上配置，您的系统就能像搭载了 V8 引擎一样，随时享受 SiliEvo 带来的稳定模型分发响应。

📱 第七部分：接入大众化图形客户端软件

绝大部分图形化客户端 (如 NextChat, ChatBox, ChatGPT-Web) 的配置皆为"套路化"操作：

寻找 "设置 (Settings)" -> "服务商设置 / 模型配置"。

选中类别：OpenAI （注意，即便是由于您要使用 Claude 或 Gemini 这类模型，在此处设置服务商分类时也必须强制选择基于 OpenAI 格式）。

填入 接口地址 (API Endpoint / Base URL)：https://api.numspirit.com/v1。

填入 秘钥 (API Key)：sk-silievo-...。

在 自定义模型 (Custom Model) 文本框内，严格照抄您想调用的模型全名，例如 qwen3.6-plus 或 anthropic/claude-sonnet-4-5。

图形客户端多媒体功能配置

对于支持图片/视频生成的客户端（如部分自定义客户端），可按照上述接口路径配置：

图片生成:

Endpoint: https://api.numspirit.com/v1/images/generations

Model: wan2.7-image 或 wan2.7-image-pro

视频生成:

Endpoint: https://api.numspirit.com/v1/videos/generations

Model: wan2.1-t2v 或 wan2.1-i2v

📚 附录：错误码速查表

错误类型	HTTP 状态码	说明	解决方案
`auth_error`	401	认证失败，API Key 无效或未提供	检查 Authorization Header 格式
`quota_exceeded`	402	额度已用尽	充值或联系客服
`invalid_request`	400	请求参数错误	检查请求体 JSON 格式和必填字段
`no_channel`	503	模型未配置有效渠道	检查 model 参数是否正确
`upstream_error`	502/500	上游 API 错误	稍后重试或联系客服

技术支持: 如有任何问题，请联系客服微信或加入服务群获取帮助。

03-模型接入

03. 广泛设备的接入与调优指南#

🛠️ 第一部分：开发者快速连通测试#

方法 1：使用 Postman#

方法 2：使用 cURL 命令行终端#

🖼️ 第二部分：图片生成接口（文生图/图生图）#

2.1 接口概览#

2.2 文生图#

🎬 第三部分：视频生成接口（文生视频/图生视频）#

3.1 接口概览#

3.2 文生视频#

3.3 视频任务状态查询#

3.4 图生视频#

3.5 支持的视频模型#

3.6 完整的视频生成工作流示例（Python）#

💻 第四部分：主流编程语言代码挂载#

2.4 文生视频 / 图生视频#

2.5 视频任务状态查询#

2.6 支持的模型列表#

2.7 完整的图片生成工作流示例（Python）#

💻 第三部分：主流编程语言代码挂载#

Python (推荐使用官方 openai 包)#

Node.js / TypeScript#

🦞 第六部分：高级场景 - 接入龙虾 (Lobster / OpenClaw) Agent 构架#

片段 1: 初始化大模型提供商 (Providers)#

片段 2: 全局 Agents 的模型路由规划 (Defaults)#

📱 第七部分：接入大众化图形客户端软件#

图形客户端多媒体功能配置#

📚 附录：错误码速查表#

03. 广泛设备的接入与调优指南

🛠️ 第一部分：开发者快速连通测试

方法 1：使用 Postman

方法 2：使用 cURL 命令行终端

🖼️ 第二部分：图片生成接口（文生图/图生图）

2.1 接口概览

2.2 文生图

🎬 第三部分：视频生成接口（文生视频/图生视频）

3.1 接口概览

3.2 文生视频

3.3 视频任务状态查询

3.4 图生视频

3.5 支持的视频模型

3.6 完整的视频生成工作流示例（Python）

💻 第四部分：主流编程语言代码挂载

2.4 文生视频 / 图生视频

2.5 视频任务状态查询

2.6 支持的模型列表

2.7 完整的图片生成工作流示例（Python）

💻 第三部分：主流编程语言代码挂载

Python (推荐使用官方 `openai` 包)

Node.js / TypeScript

🦞 第六部分：高级场景 - 接入龙虾 (Lobster / OpenClaw) Agent 构架

片段 1: 初始化大模型提供商 (Providers)

片段 2: 全局 Agents 的模型路由规划 (Defaults)

📱 第七部分：接入大众化图形客户端软件

图形客户端多媒体功能配置

📚 附录：错误码速查表