对接文档

1. 接入前准备

1. 登录本站，在控制台 → API 密钥创建令牌，选择需要使用的分组，并确认余额、额度、过期时间和模型限制。
2. 将密钥保存为环境变量 MYVIGNA_API_KEY。示例中的密钥均为占位符，需替换为你自己的密钥。
3. 先查询当前 Key 的模型列表，再复制完整模型名调用；中文、括号、线路和“原生”等后缀均是模型名的一部分。

SDK 的 Base URL 填到 /v1；直接用 HTTP 时使用下文的完整路径。不要重复拼成 /v1/v1。API Key 使用控制台颁发的令牌，不是登录密码或浏览器 Cookie。

下方 curl 使用 Bash 语法。Windows PowerShell 请用 curl.exe，将 JSON 保存为 UTF-8 request.json 后用 --data-binary @request.json；换行符与环境变量语法需要按所用终端调整。

2. 查询可用模型与分组

curl --fail-with-body "https://www.myvigna.top/v1/models" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY"

{"object":"list","data":[{"id":"YOUR_MODEL_ID","object":"model"}]}

data[].id 就是请求的 model。列表随令牌权限、分组和渠道状态变化；有模型权限不代表支持所有接口和参数。

不同分组有独立倍率、模型与质量规则。切换分组请使用绑定该分组的 Key；不要随意给请求添加 group 字段来切组。按 token、按次、按秒的模型计费方式不同，以模型详情和使用日志为准。

3. 分组与代表模型速查

每个分组是一套独立的模型池和计价规则。下面的分组名就是你后台令牌里看到的「分组」；调用时不需要在请求体里传分组，用哪个分组的 Key，就走哪个分组。

视频分组要点

视频模型的参数彼此不同，先 GET /v1/models 拿到准确模型名，再按模型说明传参。通用规律：

图片分组要点

按模型分三种入参：普通 GPT 图片走 multipart；原生 GPT / Seedream / Gemini 走 JSON 的 images[].image_url；Midjourney 使用专用模型名（带参考图请用 -ref 别名，会自动按带参考图计费）。

音乐分组要点

音乐模型（Suno、Lyria）使用音乐分组的 Key。提交后一般返回任务编号，按模型说明轮询取结果；不要把视频或图片接口的参数套用到音乐模型。

分组会随渠道调整而变化，模型清单以 GET /v1/models 和「模型广场」的实时结果为准。

4. 文本对话 · Chat Completions

curl --fail-with-body "https://www.myvigna.top/v1/chat/completions" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_CHAT_MODEL_ID","messages":[{"role":"user","content":"你好，请简短介绍自己。"}],"stream":false}'

非流式正文通常位于 choices[0].message.content。模型名用上一节返回的真实 ID 替换；图片、视频模型不能直接当作聊天模型调用。

流式输出

将 stream 改为 true，curl 添加 -N；客户端逐块读取 SSE 的 data:，拼接 choices[].delta.content，并正确处理结束标志、错误和工具调用。不要先等整个响应读完再展示。支持情况依模型和渠道而定。

curl -N "https://www.myvigna.top/v1/chat/completions"   -H "Authorization: Bearer $MYVIGNA_API_KEY"   -H "Content-Type: application/json"   -d '{"model":"YOUR_CHAT_MODEL_ID","messages":[{"role":"user","content":"你好"}],"stream":true}'

HTTP 200、心跳或思考事件不等于完整回答。工具调用参数可能分片，需拼接后执行；连接中断时不要直接重放已执行工具的请求。

5. Responses 兼容接口

curl --fail-with-body "https://www.myvigna.top/v1/responses" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_RESPONSES_MODEL_ID","input":"请用一句话介绍你自己。","stream":false}'

用于支持 Responses 的模型/分组。正文从 output[] 中 message 的 content[] / output_text 项读取，不能套用 Chat 的 choices 字段。流式使用 Responses 事件格式，不能复用 Chat SSE 解析器。客户端选用 OpenAI 兼容提供方，Base URL 同样填本站 /v1。

Claude / Gemini 等模型若通过 OpenAI 兼容协议接入，使用其实际模型名与支持的兼容接口；不能仅凭模型厂商就假定原生 Messages、generateContent 或某个工具协议可用。

6. Python 与 Node.js SDK

Python：pip install openai。环境变量设置自己的密钥与可用文本模型 MYVIGNA_MODEL。

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["MYVIGNA_API_KEY"],
    base_url="https://www.myvigna.top/v1",
    timeout=180.0,
    max_retries=0,
)
reply = client.chat.completions.create(
    model=os.environ["MYVIGNA_MODEL"],
    messages=[{"role": "user", "content": "你好"}],
)
print(reply.choices[0].message.content)

Node.js：npm install openai，保存为 example.mjs。

import OpenAI from "openai";
const client = new OpenAI({
  apiKey: process.env.MYVIGNA_API_KEY,
  baseURL: "https://www.myvigna.top/v1",
  timeout: 180000,
  maxRetries: 0,
});
const reply = await client.chat.completions.create({
  model: process.env.MYVIGNA_MODEL,
  messages: [{ role: "user", content: "你好" }],
});
console.log(reply.choices[0].message.content);

客户端若只要求“API 地址”，请留意它是否自动添加 /v1。密钥应由你自己的后端或本地客户端持有，公开前端不要嵌入服务端密钥。

7. 同步图片生成与参考图

文生图：POST /v1/images/generations；参考图：POST /v1/images/edits。模型质量档和尺寸必须匹配对应分组；以下仅展示普通 GPT 图片接口的请求结构。

curl --fail-with-body "https://www.myvigna.top/v1/images/generations" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_IMAGE_MODEL_ID","prompt":"一只橘猫坐在窗边，柔和自然光","n":1,"size":"1024x1024","response_format":"url"}'

普通 GPT 参考图使用 multipart；让客户端自动设置带 boundary 的 Content-Type。

curl --fail-with-body "https://www.myvigna.top/v1/images/edits"   -H "Authorization: Bearer $MYVIGNA_API_KEY"   -F "model=YOUR_ORDINARY_GPT_IMAGE_MODEL_ID"   -F "prompt=将图片中的杯子改为蓝色"   -F "image=@reference.png" -F "n=1"

原生 GPT 参考图使用 JSON，示例中的模型 ID 必须来自原生分组：

curl --fail-with-body "https://www.myvigna.top/v1/images/edits" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_NATIVE_IMAGE_MODEL_ID","prompt":"将图1的杯子改为蓝色","n":1,"size":"1024x1024","quality":"high","images":[{"image_url":"data:image/png;base64,REPLACE_WITH_IMAGE_BASE64"}]}'

结果可能包含 data[].url 或 data[].b64_json。url 需及时下载，外部 CDN 下载不附加本站 Key；b64_json 需 Base64 解码成图片字节。结果 JSON 不能直接改名为 PNG。请保存所有 data 项。

8. 推荐：异步生图 · 可恢复原任务

提交一次 → 保存 task_id → 查询状态 → 成功后取图。长耗时生成推荐使用本站异步接口；每次新生成使用一个新的幂等键，同次网络恢复保持原幂等键和完全相同的请求。

curl --fail-with-body "https://www.myvigna.top/v1/images/tasks" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Idempotency-Key: image-unique-request-001" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_IMAGE_MODEL_ID","prompt":"一只橘猫坐在窗边","n":1,"size":"1024x1024","response_format":"url"}'

HTTP 202
{"object":"image.task","task_id":"imgtask_…","status":"queued",
 "poll_url":"/v1/images/tasks/imgtask_…",
 "result_url":"/v1/images/tasks/imgtask_…/result","poll_after_ms":2000}

curl --fail-with-body "https://www.myvigna.top/v1/images/tasks/TASK_ID" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY"

结果接口返回 202 表示仍在处理；HTTP 200 才读取 data。所有查询均使用提交时同一把 Key。参考图使用 POST /v1/images/tasks/edits，沿用上一节对应模型格式。近期任务：GET /v1/images/tasks?limit=20。

请求体当前上限 20 MB；任务结果通常保留约 24 小时，实际以回执 expires_at 为准，图片链接可能更早失效。不要使用 /tasks/generations，也不要因超时更换幂等键重新生图。下载失败只重试原结果下载。

查看异步生图补充说明 →

9. 视频生成与取回

视频使用视频分组的 Key。若 Key 是 auto 或生图分组，调用视频会返回 503 No available channel for model <model> under group <group>，需要换成视频分组的 Key。

视频是异步任务：提交拿 id → 轮询状态 → 完成后取文件。单条通常 30 秒到 10 分钟，提交请求不要设太短超时。

提交任务

curl --fail-with-body "https://www.myvigna.top/v1/videos" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_VIDEO_MODEL_ID","prompt":"阳光穿过森林，镜头缓慢推进","seconds":5,"size":"720p","aspect_ratio":"16:9"}'

响应里保存 id：

{"id":"task_xxx","object":"video","model":"...","status":"queued","progress":0,"created_at":1793976113}

轮询任务

curl --fail-with-body "https://www.myvigna.top/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY"

状态值：queued 排队中、in_progress 生成中、succeeded 成功、failed 失败。前 2 分钟每 5 秒查一次，之后放宽到 15 秒；总超时建议给足 15 分钟。不要用 1 秒级高频轮询。

取回文件

curl --fail-with-body "https://www.myvigna.top/v1/videos/TASK_ID/content" \
  -H "Authorization: Bearer $MYVIGNA_API_KEY" \
  --output video.mp4

若查询响应里直接给了 url，那是上游临时地址，请及时转存到你自己的存储，过期后无法再取。

参数要点

• size 与 resolution 大部分模型都认，但 wan3-480p-20s / wan3-720p-20s 必须用 size，传 resolution 会报 plugin_usage_invalid。保险起见统一用 size。
• 分辨率必须在该模型支持范围内，否则报 invalid_resolution。例如 minimax-h3-f 支持 480p / 768p / 1080p，不支持 720p。
• 参考图必须是公网 HTTP(S) 直链，不支持本地上传（会报 Video references require public HTTP(S) URLs）。私有存储请生成有效期 ≥30 分钟的签名链接。
• 提交时按最坏情况预扣额度，完成后按实际结算，失败会退还。余额建议留 20% 余量，否则会出现「明明够钱却报余额不足」。
• 失败不要原样重试：多半是提示词或素材触发上游审核，重试大概率继续失败，还会重复扣费。
• 超时不等于任务停止。已拿到 task_id 就查原任务，不要重新 POST（会二次计费）。
• 同一 Key 大量并发提交会被上游排队，表现为长时间停在 queued；单 Key 并发建议不超过 3~5 个。

10. 图片模型各档位参数与注意事项

下表把当前生图分组里的档位、分辨率口径、quality 与参考图能力对齐。模型名里的括号、线路和「原生 / 满血 / 稳定 / 4k」后缀都是模型名的一部分，必须整串传入。

通用规则

注意事项

1. 提示词为空白字符串会被拒（400）；size 与 resolution 不要同时传。
2. 参考图建议单张 ≤1.4 MB、单边 ≤2048；过大的图先压缩，否则容易 400 或超时。
3. 任务已失败或结果未确认时不要自动重发：凭 task_id 查原任务；失败任务不计费。
4. grok-imagine-image-2.0 暂不支持图片编辑（只能文生图）：带参考图会被拒绝，且不产生任务、不扣费。
5. seedream-5.0-pro 只读参考图、不按图生图，出图固定方图；要真正图生图请用 seedream-5.0-lite。
6. Midjourney / niji 带参考图请用 -ref 别名，它会自动按带参考图计费；基础别名只做文生图。
7. Gemini 图片模型的分辨率与比例写在 extra_fields.gemini_image_config 的 imageSize 与 aspectRatio 里，不支持任意像素尺寸。

11. 视频模型各档位参数与注意事项

下表是当前视频分组实际可用的 21 个模型，参数与价格取自各模型的当前配置。未列出的模型名调用会返回 400。

11.1 按秒计费（费用 = 单价 × 实际时长）

单位：元/秒。seedance 系列特别注意：带参考视频时，计费时长 = 生成时长 + 参考视频实际总时长。例如生成 4 秒、参考视频 6 秒，按 10 秒计费。

11.2 按条计费（固定价格，与时长无关）

按条计费的模型，提交时传的 seconds 只在允许范围内校验，不影响价格。标「固定」的分辨率或时长，传其它值无效。

11.3 参数注意事项

1. 分辨率超出范围会被拒：报 invalid_resolution。典型例子是 minimax-h3-f 支持 480p / 768p / 1080p，不支持 720p。
2. wan3 系列必须用 size：wan3-480p-20s / wan3-720p-20s 传 resolution 会报 plugin_usage_invalid: plugin usage enum is not an allowed value。
3. 时长超出范围会被拒：报 invalid_duration。固定时长的模型（如 wan3 固定 20 秒、sd2.5-满血301010-线路1 固定 30 秒）传别的值无意义。
4. 参考素材必须是公网直链：图片 / 视频 / 音频都要公网 HTTP(S) 地址，本地文件先上传拿 URL 再提交。
5. 参考素材有数量上限：见上表最后一列。sd2.0-满血-903-线路3 不支持参考视频，只支持图片和音频。
6. 预扣机制：提交时按最大时长和最高分辨率预扣，完成后按实际结算。余额不足会报 insufficient_user_quota。
7. 计费配置异常：若报 model_price_error: fixed pricing is not supported for task usage expressions，说明该模型的计费表达式配置有问题，请联系管理员。

11.4 选型建议

12. 常见错误与排查

排查时提供：请求时间、模型完整名称、接口路径、HTTP 状态、任务号/请求号和错误内容。不要提供完整密钥。调用是否扣费及金额以本站使用日志与账单为准。