这份文档是干什么的？

如果你打开 Swagger 看到一堆英文参数看不懂，看这一份就够了。 这里用中文说明：怎么拿密钥、怎么发请求、每个字段是什么意思、常见报错怎么处理。

技术同学需要完整字段定义时，可再看 Swagger 接口参考。 网站用户（非 API）请看 本站使用说明。

三步上手

1. 在 产品站 注册并登录。
2. 进入 用户中心 → 开发者 API，点击「生成 API Key」，复制以 synex_ 开头的密钥（只显示一次，请保存好）。
3. 把下面命令里的 你的密钥 换成真实 Key，在终端执行（把域名换成你的站点）：

curl https://你的域名/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 你的密钥" \
  -d '{"model":"openai/gpt-4o-mini","stream":false,"messages":[{"role":"user","content":"你好，用一句话介绍你自己"}]}'

成功时会返回 JSON，里面包含 AI 的回复文字。每次调用会扣除账户积分。

认证：每次请求都要带密钥

推荐在 HTTP 请求头里加：

X-API-Key: synex_xxxxxxxxxxxxxxxx

也支持把 Key 放在 Authorization 头（效果相同）：

Authorization: Bearer synex_xxxxxxxxxxxxxxxx

先搞懂这几个词

常用接口一览

生图、生视频与 SynexAI聊天室共用同一套接口与积分；视频为异步任务，需轮询直到完成。

POST /chat — 文字对话

最常用的接口。发一段用户问题，拿回 AI 回答。

请求体参数

附件（multipart）

与网页聊天室相同，可在 multipart/form-data 请求中附带图片、视频或文档（PDF / Word / Excel / TXT 等，单文件 ≤ 10MB）。模型须支持文档输入（见 GET /studio/models 或模型列表中的 file 能力）。联网搜索与文档附件不可同请求。

示例：单轮问答

{
  "model": "openai/gpt-4o-mini",
  "stream": false,
  "messages": [
    { "role": "user", "content": "用三句话介绍 SynexAI 能做什么" }
  ]
}

示例：多轮对话（带上下文）

{
  "model": "openai/gpt-4o-mini",
  "stream": false,
  "messages": [
    { "role": "user", "content": "我想写小红书种草文案" },
    { "role": "assistant", "content": "好的，请告诉我产品名称和目标人群。" },
    { "role": "user", "content": "产品是保湿面霜，目标人群是 25 岁左右的女生" }
  ]
}

返回结果怎么读？

非流式时，回复文字一般在：

data.choices[0].message.content

若开启了兼容模式，也可能直接在顶层 choices 里，和 OpenAI 官方格式类似。

GET /models — 查可用模型

调用聊天前，建议先拉一次模型列表，从返回里选 available: true 的 id 填到 model 字段。

curl https://你的域名/models \
  -H "X-API-Key: 你的密钥"

返回里重点看：

• data.default — 推荐默认模型 ID
• data.models[].id — 模型标识，复制到 /chat 的 model
• data.models[].available — false 表示当前积分/权限不可用

POST /vision — 识图

上传一张图片，让 AI 用中文描述或回答你的问题。

方式一：JSON（图片用网址或 Base64）

{
  "model": "openai/gpt-4o-mini",
  "prompt": "请详细描述这张图片",
  "imageUrl": "https://example.com/photo.jpg"
}

prompt 也可写成 question 或 text，意思相同。

方式二：表单上传文件（curl）

curl https://你的域名/vision \
  -H "X-API-Key: 你的密钥" \
  -F "model=openai/gpt-4o-mini" \
  -F "prompt=图里有什么？" \
  -F "image=@/path/to/photo.jpg"

表单字段名可用 image、images、file 或 files。

识图前先查模型

curl https://你的域名/vision/models \
  -H "X-API-Key: 你的密钥"

GET /studio/models — 查生图 / 生视频模型

聊天室能力（生图、朗读、音乐、视频）的模型列表都在这里，和网页里切换模型是同一数据源。

curl https://你的域名/studio/models \
  -H "X-API-Key: 你的密钥"

返回里重点看：

• data.models.image — 生图模型列表，取 id 填到 /studio/image 的 model
• data.models.video — 生视频模型，取 id 填到 videoModel
• data.recommended — 各能力推荐模型
• available: false — 当前积分不足或未充值，暂不可用

POST /studio/image — 生图（文生图 / 图生图）

使用 multipart/form-data 表单（不是 JSON）。同步返回，一般需等待 30 秒～数分钟。

表单字段

示例：纯文生图

curl https://你的域名/studio/image \
  -H "X-API-Key: 你的密钥" \
  -F "prompt=赛博朋克风格城市夜景，霓虹灯，电影感" \
  -F "model=google/gemini-2.5-flash-image" \
  -F "aspectRatio=16:9"

示例：图生图（带参考图）

curl https://你的域名/studio/image \
  -H "X-API-Key: 你的密钥" \
  -F "prompt=保持产品主体，换成圣诞红色氛围背景" \
  -F "model=google/gemini-2.5-flash-image" \
  -F "images=@/path/to/product.jpg"

返回结果

{
  "success": true,
  "data": {
    "images": ["/studio/canvas-assets/用户ID/xxx.png"],
    "caption": "可选的 AI 说明文字",
    "model": "实际使用的模型 ID"
  },
  "meta": { "creditsCharged": 120, "creditsBalance": 880 }
}

images 里是图片地址。下载时在请求头带上同一个 X-API-Key：

curl "https://你的域名/studio/canvas-assets/用户ID/xxx.png" \
  -H "X-API-Key: 你的密钥" \
  -o result.png

POST /video/projects — 生视频（异步）

视频不能像聊天一样「一次请求立刻返回」。流程是：提交任务 → 轮询状态 → 完成后下载 MP4。 网页里的「生成视频」走的就是这套接口。

模式 mode=ai_full（文生视频 / 图生视频）

根据文字描述（和可选参考图）生成短视频，最常用。

示例：提交文生视频任务

curl https://你的域名/video/projects \
  -H "X-API-Key: 你的密钥" \
  -F "mode=ai_full" \
  -F "prompt=一只橘猫在窗台上晒太阳，写实风格，慢镜头" \
  -F "videoModel=google/veo-3.1-lite" \
  -F "aspectRatio=16:9" \
  -F "durationSec=8"

成功返回 HTTP 202，表示任务已排队：

{
  "success": true,
  "data": {
    "project": { "id": "vp_abc123", "status": "queued", ... },
    "pollUrl": "/video/projects/vp_abc123"
  }
}

轮询任务状态

curl https://你的域名/video/projects/vp_abc123 \
  -H "X-API-Key: 你的密钥"

data.project.status 常见值：

• queued — 排队中
• generating_video — 正在生成画面
• compositing — 合成中
• completed — 完成，此时 outputUrl 有 MP4 下载地址
• failed — 失败，看 error 字段

建议每 5～10 秒轮询一次，直到 completed 或 failed。高端模型可能需要数分钟。

限流说明：GET /video/projects/{id} 状态查询不计入 POST /chat 的每分钟 30 次限制；仅 POST /video/projects 创建任务受 chat 限流。遇 429 请退避重试。

curl "https://你的域名/studio/projects/vp_abc123/final.mp4?..." \
  -H "X-API-Key: 你的密钥" \
  -o video.mp4

outputUrl 是带签名的完整路径，直接复制响应里的 URL 即可，不必手拼。

模式 mode=compose（素材合成，进阶）

上传已有视频，自动加 BGM / 配音后输出新 MP4。需额外字段：

• sourceVideo — 视频文件（必填）
• script — 旁白文案（开启配音时）
• voiceEnabled — 1 开配音，0 关
• voiceMode — tts 智能朗读 或 clone 声音克隆
• voiceReference — 克隆模式下的参考音频（3～25 秒）

素材合成 27 积分/次；与 AI 文生视频计费不同。

生图 / 生视频：Python 完整示例

import time
import requests

API_BASE = "https://你的域名"
HEADERS = {"X-API-Key": "synex_你的密钥"}

def generate_image(prompt: str) -> list[str]:
    r = requests.post(
        f"{API_BASE}/studio/image",
        headers=HEADERS,
        files={"prompt": (None, prompt), "aspectRatio": (None, "1:1")},
        timeout=300,
    )
    r.raise_for_status()
    return r.json()["data"]["images"]

def generate_video(prompt: str, poll_sec: int = 8) -> str:
    r = requests.post(
        f"{API_BASE}/video/projects",
        headers=HEADERS,
        data={
            "mode": "ai_full",
            "prompt": prompt,
            "aspectRatio": "16:9",
            "durationSec": "5",
        },
        timeout=60,
    )
    r.raise_for_status()
    project_id = r.json()["data"]["project"]["id"]
    while True:
        p = requests.get(f"{API_BASE}/video/projects/{project_id}", headers=HEADERS, timeout=30)
        p.raise_for_status()
        proj = p.json()["data"]["project"]
        if proj["status"] == "completed":
            return proj["outputUrl"]
        if proj["status"] == "failed":
            raise RuntimeError(proj.get("error") or "video failed")
        time.sleep(poll_sec)

# print(generate_image("极简风咖啡海报"))
# print(generate_video("夕阳下的海边，电影感慢镜头"))

用 Python 调用聊天（复制即用）

import requests

API_BASE = "https://你的域名"   # 不要末尾斜杠
API_KEY = "synex_你的密钥"

def chat(user_text: str) -> str:
    r = requests.post(
        f"{API_BASE}/chat",
        headers={
            "Content-Type": "application/json",
            "X-API-Key": API_KEY,
        },
        json={
            "model": "openai/gpt-4o-mini",
            "stream": False,
            "messages": [{"role": "user", "content": user_text}],
        },
        timeout=120,
    )
    r.raise_for_status()
    body = r.json()
    # 统一信封格式
    data = body.get("data", body)
    return data["choices"][0]["message"]["content"]

if __name__ == "__main__":
    print(chat("你好"))

用 JavaScript 调用

const API_BASE = "https://你的域名";
const API_KEY = "synex_你的密钥";

async function chat(userText) {
  const res = await fetch(`${API_BASE}/chat`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({
      model: "openai/gpt-4o-mini",
      stream: false,
      messages: [{ role: "user", content: userText }],
    }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message || res.statusText);
  const data = body.data ?? body;
  return data.choices[0].message.content;
}

chat("你好").then(console.log);

常见错误与处理

计费说明

• API 调用与网页聊天共用同一积分钱包（赠送积分与充值积分分开记账）。
• 新用户注册赠送 50 赠送积分；邀请码可选，填写后双方额外各得 15 赠送积分。
• 经济型聊天与生图等可用赠送积分；旗舰与顶级（ultra）需充值或各能力月 3 次试用（二者共用）；视频月 3 次试用全模型共用。
• 有充值积分余额后不受软日限；无充值积分用户有按能力日限（如 chat 500/天）。
• 充值包默认 10 积分/元（¥49→490 等），详见产品站「积分充值」。
• 仅使用网站（非 API）请看 本站使用说明（含 积分与充值、邀请好友、手机与电脑）。

还有问题？

• 网页里试调：Demo 演示页
• 完整字段列表：Swagger 接口参考
• 管理密钥：产品站 → 用户中心 → 开发者 API