云集智能 API 文档 · 国内 Agnes 代理

📖 介绍

云集智能 API 是 Agnes AI 平台的国内代理网关。我们做三件事：

稳定的 Key 池：聚合多账号的 Key，单 Key 异常自动切换，避免您自己管理多个 Agnes 账号
国内直连：本站直接连通 Agnes 上游，绕开官方 API 在国内的不稳定问题
统一鉴权：用 sk-yj-xxx 单 Key 调用，不暴露上游细节

💡 我们能用来做什么？
· 在自己的产品/网站里集成 AI 视频、图片能力
· 跑自动化脚本批量生成内容
· 测试对比模型效果

🚀 快速开始（3 步上手）

1. 获取你的 API Key

登录后，在「我的」→ API 接入 Tab 看到你的 sk-yj-xxx 格式 Key。

2. 选一个端点

下面是最小可运行示例（图片生成）：

curl https://ai.yunjii.cn/v1/images/generations \
  -H "Authorization: Bearer sk-yj-你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "一只在太空漂浮的橘猫，电影感"
  }'

3. 看响应

成功会返回 JSON，包含图片 URL：

{
  "data": [
    {
      "url": "https://storage.googleapis.com/.../image.png"
    }
  ]
}

✅ 成功了？ 接下来看端点参考了解完整参数，或代码示例看 Python / JS 怎么写。

🔐 认证

所有 API 请求都必须在 Header 里带 Bearer Token：

Authorization: Bearer sk-yj-你的key

⚠️ 安全提醒：Key 相当于你账号的密码。
· 不要提交到 GitHub / 公开页面
· 怀疑泄漏时立刻在我的 → API 接入 → 重新生成

🧠 模型列表

agnes-image-2.1-flash 同步

图片生成。同步响应，秒级出图。支持文生图、图生图、组合/保留、高密度优化。

agnes-video-v2.0 异步

视频生成。需要先提交任务（POST /v1/videos），再轮询结果（GET /v1/videos/{id}）。支持文生视频、图生视频、多图视频、关键帧动画。

📡 端点参考

POST/v1/images/generations

文生图 / 图生图。同步返回图片 URL。

请求参数

参数	类型	必填	说明
`model`	string	✓	固定 `agnes-image-2.1-flash`
`prompt`	string	✓	图片描述文本
`image`	string \| string[]	✗	参考图 URL（图生图/组合/保留时使用）
`size`	string	✗	如 `1024x1024`、`1024x1792`
`seed`	int	✗	固定种子可复现结果
`n`	int	✗	生成张数，默认 1

响应

{
  "data": [
    { "url": "https://storage.googleapis.com/.../abc.png" }
  ]
}

POST/v1/videos

提交视频生成任务。立即返回 task_id，需要轮询查询结果。

请求参数

参数	类型	必填	说明
`model`	string	✓	固定 `agnes-video-v2.0`
`prompt`	string	✓	视频描述文本
`image`	string	✗	单张参考图 URL（图生视频）
`extra_body.image`	string[]	✗	多张参考图 URL（多图视频/关键帧）
`extra_body.mode`	string	✗	多图模式时填 `"keyframes"`
`height`	int	✗	视频高度，默认 768
`width`	int	✗	视频宽度，默认 1152
`num_frames`	int	✗	帧数。必须满足 `8n+1` 且 ≤ 441
`frame_rate`	int	✗	帧率 1-60，默认 24
`seed`	int	✗	随机种子
`negative_prompt`	string	✗	反向描述（不想出现的内容）

响应

{
  "id": "task_xxxxx",
  "object": "video",
  "model": "agnes-video-v2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1774344160
}

GET/v1/videos/{task_id}

查询视频任务状态。轮询直到 status="completed"。

状态机

状态	说明	建议
`queued`	排队中	继续轮询
`in_progress`	生成中	3 秒一次轮询，看 progress
`completed`	完成	读取 `video_url` 或 `remixed_from_video_id.video_url`
`failed`	失败	看 `error` 字段，常见原因：参数超限/上游限流

💻 调用示例

cURL

# 文生图
curl https://ai.yunjii.cn/v1/images/generations \
  -H "Authorization: Bearer $YJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agnes-image-2.1-flash","prompt":"赛博朋克街道"}'

# 文生视频
curl -X POST https://ai.yunjii.cn/v1/videos \
  -H "Authorization: Bearer $YJ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cat walking on the beach at sunset",
    "num_frames": 121,
    "frame_rate": 24
  }'

Python (requests)

import requests, time

API_KEY = "sk-yj-你的key"
BASE = "https://ai.yunjii.cn/v1"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 文生图
r = requests.post(f"{BASE}/images/generations",
    headers=H,
    json={"model": "agnes-image-2.1-flash", "prompt": "宇航员在火星"})
print(r.json()["data"][0]["url"])

# 文生视频（异步）
r = requests.post(f"{BASE}/videos",
    headers=H,
    json={"model": "agnes-video-v2.0", "prompt": "A dancing robot", "num_frames": 121})
task_id = r.json()["id"]

# 轮询
while True:
    s = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
    print(f"状态: {s['status']}  进度: {s.get('progress', 0)}%")
    if s["status"] == "completed":
        print("视频 URL:", s.get("video_url") or s.get("remixed_from_video_id", {}).get("video_url"))
        break
    if s["status"] == "failed":
        print("失败:", s.get("error"))
        break
    time.sleep(3)

Node.js (fetch)

const API_KEY = "sk-yj-你的key";
const BASE = "https://ai.yunjii.cn/v1";
const H = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 文生图
const img = await fetch(`${BASE}/images/generations`, {
  method: "POST", headers: H,
  body: JSON.stringify({ model: "agnes-image-2.1-flash", prompt: "夜空" })
}).then(r => r.json());
console.log(img.data[0].url);

// 文生视频 + 轮询
async function generateVideo(prompt) {
  const t = await fetch(`${BASE}/videos`, {
    method: "POST", headers: H,
    body: JSON.stringify({ model: "agnes-video-v2.0", prompt, num_frames: 121 })
  }).then(r => r.json());
  const id = t.id;
  while (true) {
    const s = await fetch(`${BASE}/videos/${id}`, { headers: H }).then(r => r.json());
    console.log(s.status, s.progress);
    if (s.status === "completed") return s.video_url || s.remixed_from_video_id?.video_url;
    if (s.status === "failed") throw new Error(JSON.stringify(s.error));
    await new Promise(r => setTimeout(r, 3000));
  }
}

❌ 错误码

HTTP	含义	处理建议
401	未提供 Key 或 Key 无效	检查 Authorization 头；重新生成 Key
403	Key 被禁用	用户可能触发了安全规则，重新生成 Key
429	调用频率超限	加退避重试，或绑定更多 Agnes Key 提高配额
500	上游服务异常	30 秒后重试；多次失败联系我们
502/503	网关问题	同上
`guest_limit` (401)	游客免费次数用完	登录后即可继续使用

Key 自动切换：当你的某个 Key 触发 401/403/429 错误时，网关会自动用其他 Key 重试。响应头 X-Key-Fallback: true 表示走了兜底。

❓ FAQ

Q: 调用次数有限制吗？

登录用户：基于你绑定的 Agnes Key 的配额，绑定越多配额越高。游客：每天 3 次免费。

Q: 视频生成大概多久？

看帧数和分辨率。一般 121 帧（5 秒）需要 1-3 分钟；441 帧（最长）需要 5-10 分钟。建议每 3 秒轮询一次。

Q: Key 泄漏了怎么办？

立刻在「我的」→ API 接入 → 重新生成。旧 Key 立即失效。

Q: 跟官方 API 有什么区别？

接口协议完全一致，只是域名换成 ai.yunjii.cn，Key 用我们生成的 sk-yj-xxx。其他参数、响应格式、错误码都和官方对齐。

Q: 能在 OpenAI SDK 里直接用吗？

部分可以。把 base_url 设成 https://ai.yunjii.cn/v1，api_key 设成你的 sk-yj-xxx，但 只支持图片生成（OpenAI 兼容），视频端点需要用 Agnes 自己的协议。