AIGC 平台 API 接入文档（面向 Agent / 开发者）

本接口让你（任何 agent / 程序 / 业务系统）用你自己的一个 API Key，调用 AIGC 平台（「青龙画图 / 青龙视频」）的生成能力：文生图、图生图、文生视频、图生视频、语音合成、语音转文字。

接口采用 OpenAI 兼容风格（字段名、Bearer 鉴权、data[] 返回），便于迁移。图片为同步返回，视频为异步任务（提交后轮询）。

一、基础信息

• Base URL：https://aigc.jczxai.com
• 认证方式：每个请求都带 Authorization: Bearer <你的 Key>（见第二节）
• 请求/响应格式：application/json
• 计费：调用会产生费用，从你的账户余额扣除；余额不足时接口返回 402。

所有 /v1/* 接口都必须带 Bearer Key。未带或无效一律返回 401。

二、鉴权：用你的一把 Key

直接用你在 atp.jczxai.com 那把 API Key（access_token，sk-...） 即可，无需任何额外配置。

调用时把 Key 放进请求头：

curl -X POST https://aigc.jczxai.com/v1/images/generations \
  -H "Authorization: Bearer <你的ATP Key>" -H "Content-Type: application/json" \
  -d '{"model":"a1","prompt":"一只橘猫","size":"1024x1024"}'

• 前提：你是 atp.jczxai.com 的用户，Key 为你自己账号的 access_token（个人中心可见的 sk-...）。
• 用别人的、编造、或已失效的 token 都会被拒绝（401）。

三、模型发现：GET /v1/models

返回各能力下的模型列表（key / 名称 / 规格），供你选择模型。

curl https://aigc.jczxai.com/v1/models -H "Authorization: Bearer <你的Key>"

响应示例：

{
  "capabilities": {
    "text-to-image": [
      {"key": "a1", "name": "青龙画图 旗舰版", "output_formats": ["jpeg"], "optimization_modes": ["standard","fast"]},
      {"key": "a2", "name": "青龙画图 增强版"},
      {"key": "a3", "name": "青龙画图 轻量版"}
    ],
    "image-to-image": [
      {"key": "b1", "name": "青龙图生图"},
      {"key": "b2", "name": "青龙图生图 增强版"},
      {"key": "b3", "name": "青龙图生图 轻量版"}
    ],
    "text-to-video": [
      {"key": "c1", "name": "青龙视频", "resolutions": ["480p","720p","1080p","4K"]},
      {"key": "c2", "name": "青龙视频 极速版"},
      {"key": "c3", "name": "青龙视频 轻量版"},
      {"key": "c4", "name": "青龙视频 旗舰版", "resolutions": ["480p","720p","1080p"]}
    ],
    "image-to-video": [
      {"key": "d1", "name": "青龙视频"},
      {"key": "d2", "name": "青龙视频 极速版"},
      {"key": "d3", "name": "青龙视频 轻量版"},
      {"key": "d4", "name": "青龙视频 旗舰版", "resolutions": ["480p","720p","1080p"]}
    ]
  }
}

模型 key 速查：

model 字段也接受模型名称（如 青龙画图 旗舰版）。不填 model 则用该能力默认模型。

四、余额：GET /v1/balance

curl https://aigc.jczxai.com/v1/balance -H "Authorization: Bearer <你的Key>"

{"username": "你的账号", "balance": 12.3456, "currency": "USD"}

余额不足时创建任务会返回 402（见错误码）。

五、文生图（同步）：POST /v1/images/generations

同步返回结果。参考图较小约 8 秒；尺寸较大（2K/4K）约 60~150 秒，请把客户端超时设 ≥ 240 秒（见「注意事项」）。

请求：

{
  "model": "a1",
  "prompt": "一只趴在窗台晒太阳的橘猫，写实摄影，柔光",
  "n": 1,
  "size": "1024x1024",
  "style": "realistic",
  "negative_prompt": "模糊，畸变",
  "output_format": "jpeg",
  "prompt_optimization": "speed",
  "response_format": "url"
}

curl：

curl -X POST https://aigc.jczxai.com/v1/images/generations \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"model":"a1","prompt":"一只橘猫","n":1,"size":"1024x1024","style":"realistic"}'

响应：

{
  "created": 1720000000,
  "data": [
    {"url": "https://aigc.jczxai.com/uploads/1720000000_123.png", "mime_type": "image/png"}
  ],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

字段说明：

• 返回的 url 为公网可直接下载的 HTTPS 地址。
• response_format 传 b64_json 时额外返回 data[].b64_json（base64 图，可内联）。
• n 生成多张时返回多个 data[]。

六、图生图（同步）：POST /v1/images/edits

支持两种请求体：JSON（参考图用 data URL 或公网 URL）或 multipart/form-data（OpenAI 官方风格）。

方式一：JSON：

# 单图：image_url 或 image（data URL / 公网 URL）
curl -X POST https://aigc.jczxai.com/v1/images/edits \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"model":"b2","prompt":"把这个房间改成夏日午后阳光感","image":"data:image/png;base64,iVBORw0KGgo...","size":"1024x1024"}'

# 多图（最多 10 张）：images 数组
curl -X POST https://aigc.jczxai.com/v1/images/edits \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"model":"b2","prompt":"融合这两张图的风格","images":["data:image/png;base64,...","https://example.com/ref.png"]}'

方式二：multipart（OpenAI 官方格式）：

curl -X POST https://aigc.jczxai.com/v1/images/edits \
  -H "Authorization: Bearer <你的Key>" \
  -F "model=b2" -F "prompt=改成夏日午后阳光" -F "size=1024x1024" \
  -F "image=@/path/to/ref.png"

响应与文生图相同：{created, data:[{url,...}], usage}。

大小限制：请求体 ≤ 15MB；单张 base64 图建议 <10MB。

七、视频生成（异步）：POST /v1/videos/generations

视频生成耗时较长（1~15 分钟），采用提交任务 → 轮询。提交后立即返回任务 id，用 GET /v1/tasks/{id} 或 GET /v1/videos/{id} 轮询。

文生视频：

curl -X POST https://aigc.jczxai.com/v1/videos/generations \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"model":"c1","prompt":"无人机从山谷树林上空掠过，电影质感","resolution":"720p","duration":10,"ratio":"16:9","generate_audio":true}'

图生视频：

curl -X POST https://aigc.jczxai.com/v1/videos/generations \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"model":"d1","prompt":"让这座建筑慢慢长出藤蔓和鲜花","image":"https://example.com/building.png","first_frame_image":"https://example.com/start.png","last_frame_image":"https://example.com/end.png","resolution":"720p","duration":10,"ratio":"16:9","return_last_frame":true}'

响应（立即返回任务 id）：

{"id": 42, "status": "in_progress", "model": "c1", "created_at": 1720000000}

参数说明：

• image_url(单图) / images(多图) → 参考图（图生视频最多 9 张）
• first_frame_image / last_frame_image → 首帧/尾帧（不能与参考图同时用）
• resolution：480p/720p/1080p/4K（按模型支持档位）
• duration：4~15 秒，可设任意值（如 5 / 10 / 15）——并不是固定 5 秒；不传时约 4 秒
• ratio：16:9/9:16/1:1/4:3/3:4/21:9/adaptive（默认 16:9）
• generate_audio：布尔，是否生成音频
• return_last_frame：布尔，是否额外返回尾帧图

轮询任务状态

# 通用任务接口（图片/视频都可用）
curl https://aigc.jczxai.com/v1/tasks/42 -H "Authorization: Bearer <你的Key>"

# OpenAI sora 风格视频接口
curl https://aigc.jczxai.com/v1/videos/42 -H "Authorization: Bearer <你的Key>"

GET /v1/tasks/{id} 响应：

{
  "id": 42,
  "type": "text-to-video",
  "model_key": "c1",
  "status": "done",
  "error_msg": "",
  "results": [
    {"url": "https://aigc.jczxai.com/uploads/xxx.mp4", "path": "/uploads/xxx.mp4", "mime_type": "video/mp4", "thumb_url": "https://aigc.jczxai.com/uploads/xxx_thumb.jpg"}
  ]
}

GET /v1/videos/{id} 响应：

{"id": 42, "status": "completed", "model": "c1", "url": "https://.../xxx.mp4", "thumb_url": "https://.../xxx_thumb.jpg", "error": "", "created_at": 1720000000}

轮询建议：status 从 in_progress → completed / failed。每 5~10 秒轮询一次。

八、语音：合成 / 转写

查看可选音色：GET /v1/speech/voices

curl https://aigc.jczxai.com/v1/speech/voices -H "Authorization: Bearer <你的Key>"
# → {"default":"zh_female_shuangkuaisisi_moon_bigtts","voices":[{"id":"...","name":"爽快思思","gender":"female","is_default":true}, ...]}

• 调语音合成时把某个 id 填到 voice 即可换音色；不传用默认音色。
• 📄 音色库一览（全部可选音色的 id / 中文名 / 性别 / 代数，方便挑音色）：https://aigc.jczxai.com/static/docs/voices.html

文本转语音（同步）：POST /v1/audio/speech

curl -X POST https://aigc.jczxai.com/v1/audio/speech \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"input":"你好，欢迎使用 AIGC 语音","voice":"zh_female_shuangkuaisisi_moon_bigtts"}'

• 默认返回 audio/mpeg 音频字节（可直接保存/播放）。
• response_format 传 b64 时返回 JSON：

{"base64": "<base64音频>", "content_type": "audio/mpeg", "chars": 12}

音频转文本：POST /v1/audio/transcriptions

支持 multipart（file 字段）或 JSON（audio 为 base64/data URL）：

# 方式一：multipart
curl -X POST https://aigc.jczxai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer <你的Key>" \
  -F "file=@/path/to/audio.mp3"

# 方式二：JSON（base64）
curl -X POST https://aigc.jczxai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer <你的Key>" -H "Content-Type: application/json" \
  -d '{"audio":"data:audio/mpeg;base64,SUQzAwAAAA...","format":"mp3"}'

响应：

{
  "text": "你好，今天天气怎么样",
  "duration_ms": 4300,
  "utterances": [{"text": "你好，今天天气怎么样", "start_time": 0, "end_time": 4300}]
}

• 支持格式：ogg / mp3 / wav / m4a / webm。

文本转语音（流式）：POST /v1/audio/speech/stream

与同步 /v1/audio/speech 同入参，但以 Server-Sent Events（SSE） 方式把音频逐块返回，调用方收到一块即可开始解码播放，不必等整句读完（适合实时播报/流式播放）：

curl -N -X POST https://aigc.jczxai.com/v1/audio/speech/stream \
  -H "Authorization: Bearer ***" -H "Content-Type: application/json" \
  -d '{"input":"你好，这是一段流式语音合成测试。","voice":"zh_female_shuangkuaisisi_moon_bigtts"}'

响应是 text/event-stream，每行 data: {...}，按序有：

data: {"type":"chunk","audio":"<base64 音频分片>","chars":22}
data: {"type":"chunk","audio":"<base64 音频分片>","chars":22}
data: {"type":"done","fee":0.0001,"chars":22,"mime":"audio/mpeg"}

• chunk：一帧音频（base64）。把所有 chunk.audio 解码后按顺序拼接 = 完整音频。
• done：流结束，含本次 fee。
• 出错时任一会得到 data: {"type":"error","message":"..."}。
• 实现参考：Python 用 requests + stream=True 逐行读 data:；前端用 fetch + ReadableStream 或 EventSource(需 POST 时用 fetch流)。

使用 voice/speaker、emotion 字段与同步接口一致。

音频转文本（流式/实时）：WebSocket /v1/audio/transcriptions/stream

用于边说话边出字的实时转写。建立 WebSocket 连接后持续发送音频帧，服务端把识别到的文字实时推回：

wss://aigc.jczxai.com/v1/audio/transcriptions/stream?token=<你的Key>

• 鉴权：可用 URL 参数 ?token=<你的Key>，或请求头 Authorization: Bearer <你的Key>。
• 音频格式默认 pcm/16000/16bit/1声道；可用 query 覆盖：?format=pcm&rate=16000&channel=1&bits=16。
• 客户端发送：
• 二进制消息 = 一帧音频（建议每帧 100~200ms）；
• 文本消息 {"done":true} = 说话结束。
• 服务端实时回推（JSON 文本帧）：

{"type":"partial","text":"当前累","duration_ms":800}
{"type":"partial","text":"当前累计识别到","duration_ms":1600}
{"type":"final","text":"当前累计识别到的完整文本。","duration_ms":3200,"fee":0.0001}

• partial：累计文本（随时间增长）；final：最终完整结果（含 fee）。出错回 {"type":"error","message":"..."}。

Python 示例（websockets）：

import asyncio, json, websockets
async def rec():
    async with websockets.connect(
        "wss://aigc.jczxai.com/v1/audio/transcriptions/stream?token=***"
    ) as ws:
        # 发送音频帧（此处演示发一个 200ms 的 pcm 帧）
        await ws.send(b"\x00\x00" * 1600)   # 音频二进制帧
        await ws.send(json.dumps({"done": True}))
        async for msg in ws:
            print(msg)
asyncio.run(rec())

• 说明：partial 是实时中间结果（可能修正），以最终 final 为准。

九、错误码

统一返回：{"error":{"message":"...","type":"..."}}

生成失败常见原因：SensitiveContentDetected（含真人肖像等敏感内容）、版权、参数非法等，均在 502 的 message 里给出可读文案。

十、Python 调用示例

import time, requests, base64

BASE = "https://aigc.jczxai.com"
KEY = "sk-..."  # 你的 API Key
H = {"Authorization": f"Bearer {KEY}"}

# 1) 看模型
models = requests.get(f"{BASE}/v1/models", headers=H).json()
print("能力:", list(models["capabilities"].keys()))

# 2) 文生图（同步）
r = requests.post(f"{BASE}/v1/images/generations", headers=H,
                  json={"model": "a1", "prompt": "一只橘猫", "n": 1, "size": "1024x1024"})
img = r.json()["data"][0]["url"]
print("图片:", img)

# 3) 图生图（参考图用 base64）
with open("ref.png", "rb") as f:
    b64 = "data:image/png;base64," + base64.b64encode(f.read()).decode()
r = requests.post(f"{BASE}/v1/images/edits", headers=H,
                  json={"model": "b2", "prompt": "改成夏日午后", "image": b64})
print("变体:", r.json()["data"][0]["url"])

# 4) 文生视频（异步：提交→轮询）
task_id = requests.post(f"{BASE}/v1/videos/generations", headers=H,
                        json={"model": "c1", "prompt": "无人机掠过山谷", "resolution": "720p", "duration": 10}).json()["id"]
while True:
    s = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=H).json()
    if s["status"] == "done":
        print("视频:", s["results"][0]["url"]); break
    if s["status"] == "failed":
        print("失败:", s["error_msg"]); break
    time.sleep(5)

十一、注意事项

• Key 安全（重要）：Authorization: Bearer <Key> 是你账号的额度凭证，不要打印进日志、写进代码仓库/配置文件、明文转发。建议用环境变量 / 密钥管理服务保存。
• 计费：调用会产生费用，从账号余额扣除；余额不足创建即返回 402。可用 GET /v1/balance 查询余额。
• 图片输入：参考图支持公网 URL 或 base64 data URL；多图用 images 数组。
• 大小限制：请求体 ≤ 15MB；单图建议 <10MB。
• 同步图片超时：客户端 HTTP 超时建议 ≥ 240 秒（大尺寸/多图较慢）；若超时接口可能降级返回任务 id，可继续用 GET /v1/tasks/{id} 轮询，不会丢单。
• 生成内容标识：生成内容会带平台合规水印/标识。
• 敏感内容：涉真人肖像、版权内容可能被拒（502），请调整提示词。

十二、最小流程（三步跑通）

# 0）准备 Key（直接用你在 ATP 平台的 access_token）
KEY=<你的Key>

# 1）文生图
curl -X POST https://aigc.jczxai.com/v1/images/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"a1","prompt":"一只橘猫","size":"1024x1024"}'
# → {"created":...,"data":[{"url":"https://.../uploads/xxx.png"}],...}

# 2）视频提交
TASK=$(curl -X POST https://aigc.jczxai.com/v1/videos/generations \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"c1","prompt":"无人机掠过山谷","resolution":"720p","duration":10}' | python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")

# 3）轮询到完成
curl https://aigc.jczxai.com/v1/tasks/$TASK -H "Authorization: Bearer $KEY"