AI API Gateway

Appearance

文生图 — z_image ​

网关地址: https://ai.ospreyai.cn（公网） 模型: z_image_bf16（百度文生图） 无需后端 Bearer Token，网关 Bearer Token 即可

概述 ​

使用 z_image_bf16 模型，由文本提示词直接生成图片（纯文生图，无需上传输入图片）。任务异步执行：提交工作流 → 轮询状态 → 下载结果。任务状态查询、结果下载、图片上传等通用接口见 任务管理。

bash
export GW="https://ai.ospreyai.cn"
export API_KEY="sk-your-api-key"

接口清单 ​

用途方法路径
提交图像任务POST/api/v1/ai/image/generate
查询任务状态GET/api/v1/ai/tasks/{prompt_id}
下载结果文件GET/api/v1/ai/image/view/
查询队列GET/api/v1/ai/queue

提交任务后异步生成，需轮询 tasks/{prompt_id} 直到 status.completed=true，再下载。

提交图像生成任务 ​

POST /api/v1/ai/image/generate
Content-Type: application/json
Authorization: Bearer sk-xxx

请求体 — ComfyUI 工作流 JSON，prompt 字段内为节点定义：

bash
curl -H "Authorization: Bearer $API_KEY" -X POST "$GW/api/v1/ai/image/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {
      "62": {"inputs": {"clip_name": "qwen_3_4b.safetensors", "type": "lumina2", "device": "default"}, "class_type": "CLIPLoader"},
      "63": {"inputs": {"vae_name": "ae.safetensors"}, "class_type": "VAELoader"},
      "66": {"inputs": {"unet_name": "z_image_bf16.safetensors", "weight_dtype": "default"}, "class_type": "UNETLoader"},
      "67": {"inputs": {"text": "A cute puppy sitting on grass, sunny day, photorealistic", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
      "68": {"inputs": {"width": 1024, "height": 1024, "batch_size": 1}, "class_type": "EmptySD3LatentImage"},
      "69": {"inputs": {"seed": 12345, "steps": 30, "cfg": 4.5, "sampler_name": "res_multistep", "scheduler": "simple", "denoise": 1, "model": ["70", 0], "positive": ["67", 0], "negative": ["71", 0], "latent_image": ["68", 0]}, "class_type": "KSampler"},
      "70": {"inputs": {"shift": 3, "model": ["66", 0]}, "class_type": "ModelSamplingAuraFlow"},
      "71": {"inputs": {"text": "blurry, low quality, distorted", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
      "65": {"inputs": {"samples": ["69", 0], "vae": ["63", 0]}, "class_type": "VAEDecode"},
      "9": {"inputs": {"filename_prefix": "output", "images": ["65", 0]}, "class_type": "SaveImage"}
    }
  }'

响应：

json
{
  "prompt_id": "0871f625-65f6-4d2f-abd8-0b248dafa58f",
  "number": 99
}

关键参数 ​

节点字段说明推荐值
67text正向提示词（英文效果更佳）—
71text负向提示词"blurry, low quality, distorted"
68width / height图片尺寸1024 × 1024
69seed随机种子（不同值生成不同图片）任意整数
69steps采样步数（越高越精细）25-35
69cfgCFG 强度4-7
9filename_prefix输出文件名前缀—

提示词技巧 ​

  • 英文优先
  • 主体 + 场景 + 光影 + 风格四要素：A cute puppy sitting on grass, sunny day, photorealistic
  • 负向提示词排除不想要的特征：blurry, low quality, distorted

完整示例：生成小狗图片 ​

bash
# 1. 提交任务
RESPONSE=$(curl -s -H "Authorization: Bearer $API_KEY" -X POST "$GW/api/v1/ai/image/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": {
      "62": {"inputs": {"clip_name": "qwen_3_4b.safetensors", "type": "lumina2", "device": "default"}, "class_type": "CLIPLoader"},
      "63": {"inputs": {"vae_name": "ae.safetensors"}, "class_type": "VAELoader"},
      "66": {"inputs": {"unet_name": "z_image_bf16.safetensors", "weight_dtype": "default"}, "class_type": "UNETLoader"},
      "67": {"inputs": {"text": "A cute fluffy golden retriever puppy, big shiny eyes, sitting on grass, sunny day, photorealistic", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
      "68": {"inputs": {"width": 1024, "height": 1024, "batch_size": 1}, "class_type": "EmptySD3LatentImage"},
      "69": {"inputs": {"seed": 12345, "steps": 30, "cfg": 4.5, "sampler_name": "res_multistep", "scheduler": "simple", "denoise": 1, "model": ["70", 0], "positive": ["67", 0], "negative": ["71", 0], "latent_image": ["68", 0]}, "class_type": "KSampler"},
      "70": {"inputs": {"shift": 3, "model": ["66", 0]}, "class_type": "ModelSamplingAuraFlow"},
      "71": {"inputs": {"text": "blurry, low quality, distorted", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
      "65": {"inputs": {"samples": ["69", 0], "vae": ["63", 0]}, "class_type": "VAEDecode"},
      "9": {"inputs": {"filename_prefix": "puppy", "images": ["65", 0]}, "class_type": "SaveImage"}
    }
  }')

PROMPT_ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['prompt_id'])")
echo "任务 ID: $PROMPT_ID"

# 2. 等待约30秒后查询状态
sleep 30
STATUS=$(curl -s -H "Authorization: Bearer $API_KEY" "$GW/api/v1/ai/tasks/$PROMPT_ID")

# 3. 提取文件名并下载
FILENAME=$(echo $STATUS | python3 -c "
import sys,json
d=json.load(sys.stdin)
for node in d.values():
    for out in node.get('outputs',{}).values():
        for img in out.get('images',[]):
            print(img['filename']); exit()
")

curl -H "Authorization: Bearer $API_KEY" "$GW/api/v1/ai/image/view/?filename=$FILENAME&type=output&subfolder=" -o puppy.png
echo "图片已保存到 puppy.png"

Python 调用示例 ​

python
import json, time, urllib.request

GW = "https://ai.ospreyai.cn"
API_KEY = "sk-your-api-key"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

nodes = {
    "62": {"inputs": {"clip_name": "qwen_3_4b.safetensors", "type": "lumina2", "device": "default"}, "class_type": "CLIPLoader"},
    "63": {"inputs": {"vae_name": "ae.safetensors"}, "class_type": "VAELoader"},
    "66": {"inputs": {"unet_name": "z_image_bf16.safetensors", "weight_dtype": "default"}, "class_type": "UNETLoader"},
    "67": {"inputs": {"text": "A cute puppy sitting on grass, sunny day, photorealistic", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
    "68": {"inputs": {"width": 1024, "height": 1024, "batch_size": 1}, "class_type": "EmptySD3LatentImage"},
    "69": {"inputs": {"seed": 12345, "steps": 30, "cfg": 4.5, "sampler_name": "res_multistep", "scheduler": "simple", "denoise": 1, "model": ["70", 0], "positive": ["67", 0], "negative": ["71", 0], "latent_image": ["68", 0]}, "class_type": "KSampler"},
    "70": {"inputs": {"shift": 3, "model": ["66", 0]}, "class_type": "ModelSamplingAuraFlow"},
    "71": {"inputs": {"text": "blurry, low quality, distorted", "clip": ["62", 0]}, "class_type": "CLIPTextEncode"},
    "65": {"inputs": {"samples": ["69", 0], "vae": ["63", 0]}, "class_type": "VAEDecode"},
    "9": {"inputs": {"filename_prefix": "puppy", "images": ["65", 0]}, "class_type": "SaveImage"}
}

# 提交
req = urllib.request.Request(
    f"{GW}/api/v1/ai/image/generate",
    data=json.dumps({"prompt": nodes}).encode(),
    headers=HEADERS, method="POST",
)
prompt_id = json.loads(urllib.request.urlopen(req, timeout=30).read())["prompt_id"]

# 轮询
while True:
    r = urllib.request.Request(f"{GW}/api/v1/ai/tasks/{prompt_id}", headers=HEADERS)
    task = json.loads(urllib.request.urlopen(r, timeout=15).read())[prompt_id]
    if task["status"].get("completed"):
        break
    time.sleep(5)

# 下载
for out in task["outputs"].values():
    for img in out.get("images", []):
        url = f"{GW}/api/v1/ai/image/view/?filename={img['filename']}&type={img['type']}&subfolder={img.get('subfolder','')}"
        req = urllib.request.Request(url, headers=HEADERS)
        open(img["filename"], "wb").write(urllib.request.urlopen(req, timeout=120).read())

常见问题 ​

问题现象可能原因解决方案
401 UnauthorizedAPI Key 错误/未传检查 Authorization: Bearer sk-xxx
任务 success 但 outputs 为空命中 ComfyUI 缓存（execution_cached）提交时换个随机 seed，避免工作流完全相同
下载 404参数缺失filename / type / subfolder 必须与状态响应一致

AI API Gateway Documentation