把 API 接入

用它在你自己的程序里出图。一把密钥、一个接口，按张计费，额度就是你在本站的余额。

生产环境主机：https://72agi.com（下文示例已使用该地址）。

1 · 拿到密钥

登录后打开 我的，页面上就有你的密钥，点「复制」即可。一个账号一把，随时能换。

• 别发出去：这把密钥等同于你的账号 —— 能调接口，也能登录本站。
• 弄丢了：回「我的」就能再看到，不用找客服。
• 想作废：点「换一把」，旧密钥立刻失效。

2 · 鉴权

每个请求带一个头就行：

Authorization: Bearer YOUR_KEY

只认这个请求头。浏览器登录后的 Cookie 不能调用出图 / 音乐接口（会返回 403，code 为 studio_retired）。不要把密钥放在 URL 查询参数里 —— 那会留在访问日志里。

3 · 模型与价格

curl https://72agi.com/api/models

返回模型、每张单价（人民币）与支持的比例。价格以下单时返回的为准。

[
  {
    "id": "nano-banana-pro",
    "name": "Nano Banana Pro",
    "prices": {"1K": 0.25, "2K": 0.25, "4K": 0.25},
    "type": "image",
    "sizes": ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
  },
  {
    "id": "nano-banana-2",
    "name": "Nano Banana 2",
    "prices": {"1K": 0.25, "2K": 0.25, "4K": 0.25},
    "type": "image",
    "sizes": ["auto", "1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"]
  },
  {
    "id": "nano-banana-pro-plus",
    "name": "Nano Banana Pro+",
    "prices": {"1K": 0.35, "2K": 0.35, "4K": 0.35},
    "type": "image",
    "sizes": ["auto", "1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
  },
  {
    "id": "nano-banana-2-plus",
    "name": "Nano Banana 2+",
    "prices": {"1K": 0.35, "2K": 0.35, "4K": 0.35},
    "type": "image",
    "sizes": ["auto", "1:1", "1:4", "1:8", "2:3", "3:2", "3:4", "4:1", "4:3", "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"]
  },
  {
    "id": "gpt-image-2",
    "name": "GPT Image 2",
    "prices": {"1K": 0.25, "2K": 0.25, "4K": 0.25},
    "type": "image",
    "sizes": ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "2:1", "1:2", "21:9", "9:21"]
  },
  {
    "id": "gpt-image-2.5-flare",
    "name": "GPT Image 2.5 Flare",
    "prices": {"1K": 0.25, "2K": 0.25, "4K": 0.25},
    "type": "image",
    "sizes": ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9", "3:1", "1:3"]
  },
  {
    "id": "gpt-image-2.5-sunburst",
    "name": "GPT Image 2.5 Sunburst",
    "prices": {"1K": 0.25, "2K": 0.25, "4K": 0.25},
    "type": "image",
    "sizes": ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9", "3:1", "1:3"]
  },
  {
    "id": "image2.5-mid",
    "name": "Image 2.5 Mid",
    "blurb": "Special mid channel. Same vlk_ key. 1K only. About ¥0.1 per image.",
    "prices": {"1K": 0.10},
    "type": "image",
    "sizes": ["auto", "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "21:9", "3:1", "1:3"]
  }
]

Image 2.5 Mid（image2.5-mid）

特殊 mid 渠道。模型名写 image2.5-mid，仍用同一把 Bearer vlk_… Key，不必换 Key。单价约 ¥0.10 / 张。调用方式与其它图片模型相同：POST /api/generate，再轮询 /api/task/{id}。

分辨率：仅 1K。本模型没有 2K / 4K 选项；请求里请固定 resolution=1K，传 2K 或 4K 会返回 400。价格与画幅比例无关，仍以 /api/models 的 prices / resolutions 为准。

curl -X POST https://72agi.com/api/generate \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "prompt=a quiet mountain path in afternoon light" \
  -F "model=image2.5-mid" \
  -F "size=16:9" \
  -F "resolution=1K"

⚠ 生成前必须确认

每一次真正提交任务之前，客户端 / 工作流都必须先把本次参数完整展示给操作者确认，只有操作者明确点「确认」之后，才允许调用生成接口。未确认不得自动连发。

• 完整提示词（prompt；批量时每一条都要展示）。
• 尺寸参数：图片的 size / resolution。
• 参考图顺序：多张 refs 时按提交顺序编号展示（第 1 张、第 2 张…），顺序会影响构图，确认后再提交。
• 型号与预估费用。

通过 API / n8n / 自建机器人接入时，请在你自己的界面或对话里实现确认步骤，不要静默连发。

4 · 生成一张图

两步：提交拿到任务号，然后轮询拿结果。单张实测 100 秒上下（4K 更久），所以别用同步等待，轮询更稳 —— 断网、刷新页面都不会丢任务。

提交（multipart 表单）：

curl -X POST https://72agi.com/api/generate \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "prompt=a quiet room, cream light" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "size=16:9" \
  -F "resolution=1K"

202 {"id": "02a38b1d1b66", "status": "queued"}

轮询：

curl https://72agi.com/api/task/02a38b1d1b66

{"id": "02a38b1d1b66", "status": "processing"}

{"id": "02a38b1d1b66", "status": "succeeded",
 "url": "/outputs/02a38b1d1b66.png", "price": 0.25}

status 有四个值：queued / processing / succeeded / failed。建议每 3–5 秒轮一次。

成功时 url 是本站路径，不是服务链接。加上域名即可下载：

失败不扣额度，error 里是原因。生成成功才扣：提交时不动余额，出图成功那一刻才扣这一张的价钱。

5 · 图生图（参考图）

同一个接口，多传 refs 字段。最多 14 张，超出部分忽略。

curl -X POST https://72agi.com/api/generate \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "prompt=turn this into a watercolour" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "refs=@./source.png"

提交前请再确认参考图顺序（第 1 张最优先影响构图）。顺序不对就先调整 refs 再生成。

参考图会影响结果的构图与风格，也会拖慢出图。能少传就少传。

传 size=auto 可以保持参考图的画幅：传一张 3:2 的照片，就出 3:2 的图（吸附到该模型支持的最接近比例）。也可写 adaptive 或 自适应。

curl -X POST https://72agi.com/api/generate \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "prompt=same scene, golden hour light" \
  -F "model=gpt-image-2.5-flare" \
  -F "size=auto" \
  -F "refs=@./photo-3x2.jpg"

6 · 查额度

curl https://72agi.com/api/credits -H "Authorization: Bearer YOUR_KEY"
{"credits": 29.75, "unlimited": false, "role": "user"}

额度单位是人民币。unlimited 为 true 时不扣费（管理员）。想看「我是谁、能做什么」用 GET /api/session。

7 · 字段与限制

• 限流（按 IP）：单张生成每分钟最多 100 次，批量每分钟 2 次，音乐每分钟 30 次。超了返回 429。
• 额度不足：返回 402，body 里带 need（需要多少）与 have（还剩多少）。
• 图片保留：出来的图默认保留 10 小时。想长期留，调 POST /api/gallery/{id}/keep。
• 接入：只需要这把密钥和下面的接口地址。模型、渠道这些都不用你配置。

8 · Music (Suno 5.5 / Suno 5)

Generate full songs (vocals or instrumental) with Suno 5.5 (suno-v5.5) or Suno 5 (suno-v5). ¥0.80 per generation (≈ $0.12), each generation returns 2 tracks (mp3 + cover). Usually done in about 45–60 s (allow a few minutes when busy). Charged only when it succeeds; a failed job costs nothing.

Same flow as images: submit, get a job id, poll. API key only — Authorization: Bearer YOUR_KEY (browser cookie sessions are rejected). Body is JSON.

curl -X POST https://72agi.com/api/music \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5.5",
    "prompt": "calm lo-fi piano, gentle beat, late night",
    "instrumental": true
  }'

202 {"id": "mus_3f9c0a1b2c3d4e5f", "object": "music.job", "status": "queued",
     "model": "suno-v5.5", "price": 0.8}

Poll every 5 seconds until status is succeeded or failed:

curl https://72agi.com/api/music/mus_3f9c0a1b2c3d4e5f \
  -H "Authorization: Bearer YOUR_KEY"

{"id": "mus_3f9c0a1b2c3d4e5f", "object": "music.job", "status": "processing",
 "model": "suno-v5.5", "price": 0.8, "created": 1791385944.0, "tracks": [], "error": ""}

{"id": "mus_3f9c0a1b2c3d4e5f", "object": "music.job", "status": "succeeded",
 "model": "suno-v5.5", "price": 0.8, "created": 1791385944.0,
 "tracks": [
   {"index": 0, "audio_url": "/outputs/music/mus_3f9c0a1b2c3d4e5f_0.mp3",
    "image_url": "/outputs/music/mus_3f9c0a1b2c3d4e5f_0.jpg",
    "title": "Paper Rain", "tags": "lo-fi, piano, gentle", "duration": 157.2,
    "lyrics": "[Instrumental]"},
   {"index": 1, "audio_url": "/outputs/music/mus_3f9c0a1b2c3d4e5f_1.mp3", "...": "..."}
 ],
 "error": "", "finished": 1791386000.0, "expires_at": 1791472400.0}

{"id": "mus_...", "object": "music.job", "status": "failed", "model": "suno-v5.5", "price": 0.8, "tracks": [],
 "error": "音乐生成失败，未扣费，请稍后再试。 / Music generation failed (not charged). Please try again."}

audio_url / image_url are paths on this site: download from https://72agi.com + path. Files are kept for 24 hours (see expires_at) — save them on your side. After that the job returns expired: true and an empty tracks list.

Python:

import os, time, requests

BASE = "https://72agi.com"
H = {"Authorization": "Bearer " + os.environ["VELIN_API_KEY"]}

r = requests.post(BASE + "/api/music", headers=H, json={
    "model": "suno-v5.5",            # or "suno-v5"
    "prompt": "upbeat city-pop song about a summer night bike ride",
    "instrumental": False,
}, timeout=60)
r.raise_for_status()                  # 400 bad body, 401 bad key, 402 not enough credits, 429 rate limited
job_id = r.json()["id"]

deadline = time.time() + 15 * 60
while True:
    p = requests.get(f"{BASE}/api/music/{job_id}", headers=H, timeout=30)
    p.raise_for_status()
    job = p.json()
    if job["status"] in ("succeeded", "failed") or time.time() > deadline:
        break
    time.sleep(5)

if job["status"] != "succeeded":
    raise SystemExit(job.get("error") or "still running, poll again later")
for t in job["tracks"]:
    mp3 = requests.get(BASE + t["audio_url"], timeout=120).content
    open(f"{job_id}_{t['index']}.mp3", "wb").write(mp3)
    print(t["title"], t["duration"], "s")

Custom mode — you write the lyrics, style and title:

{"model": "suno-v5.5", "custom_mode": true, "instrumental": false,
 "title": "Summer Ride", "style": "city pop, upbeat, female vocal, 110 bpm",
 "prompt": "[Verse]\nNeon on the river...\n[Chorus]\nWe ride all night...",
 "vocal_gender": "f"}

• Models and prices: GET /api/models?type=music (or ?type=all for images + music). Plain /api/models still lists image models only.
• Status: queued → processing → succeeded / failed. Recent jobs: GET /api/music?limit=20.
• Errors (message in error): 400 invalid body; 401 missing or invalid key; 403 code studio_retired when you send a browser cookie instead of a key; 402 not enough credits (need / have); 404 unknown job id; 429 more than 30 music submissions per minute per IP; 503 code queue_full (retry after ~30 s).
• For AI agents: the ready-made skill file is at https://72agi.com/velin-agent-skill.txt (save it as SKILL.md).

curl -X POST https://72agi.com/api/video \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling4.0",
    "mode": "text_to_video",
    "prompt": "cinematic drone shot over misty mountains at sunrise",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

curl https://72agi.com/api/video/JOB_ID \
  -H "Authorization: Bearer YOUR_KEY"

充值出图额度请到 生图充值 页。