Agnes Image — Agnes Image 2.1 Flash 图像模型

概述

Agnes Image 2.1 Flash 是 Sapiens AI 提供的免费图像生成模型，提供与 OpenAI 兼容的 images API，支持文生图（text-to-image）生成和图生图（image-to-image）编辑。

• 模型 ID： agnes-image-2.1-flash
• 基础 URL： https://apihub.agnes-ai.com/v1
• 定价： 约 $0.003/张（提供免费额度）
• 认证方式： Authorization: Bearer YOUR_API_KEY
• 生成端点： POST /v1/images/generations

快速开始

API 密钥从环境变量 AGNES_API_KEY 中读取。

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGNES_API_KEY"],
    base_url="https://apihub.agnes-ai.com/v1",
)

# 文生图
resp = client.images.generate(
    model="agnes-image-2.1-flash",
    prompt="A cute cat playing soccer on a green field, sunny day, cinematic style",
    size="1024x1024",
)
print(resp.data[0].url)

cURL（文生图）

curl https://apihub.agnes-ai.com/v1/images/generations 
  -H "Authorization: Bearer $AGNES_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A futuristic city at sunrise, cinematic realism",
    "size": "1024x768",
    "extra_body": {"response_format": "url"}
  }'

cURL（图生图）

curl https://apihub.agnes-ai.com/v1/images/generations 
  -H "Authorization: Bearer $AGNES_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "Turn the scene into a rainy cyberpunk night with neon lights",
    "size": "1024x768",
    "extra_body": {
      "image": ["https://example.com/input.png"],
      "response_format": "url"
    }
  }'

端点

请求参数

响应格式

{
  "created": 1780000000,
  "data": [
    {
      "url": "https://storage.googleapis.com/agnes-aigc/xxx.png",
      "b64_json": null,
      "revised_prompt": null
    }
  ]
}

通过 data[0].url 访问图像；若使用 base64 输出，则读取 data[0].b64_json。

能力

1. 文生图（Text-to-Image）

根据文本描述生成图像。建议使用结构化提示词，包含以下要素：

[主体] + [场景/环境] + [风格] + [光线] + [构图] + [质量要求]

示例：A futuristic city marketplace, flying vehicles, holographic signs, dense crowds, neon lighting, cinematic realism, ultra-detailed

2. 图生图（Image-to-Image）

在保留原图结构的前提下对现有图像进行编辑。通过 extra_body.image 提供输入图像 URL：

edit = client.images.generate(
    model="agnes-image-2.1-flash",
    prompt="Keep the cat and soccer ball, change scene to snowy winter field",
    size="1024x1024",
    extra_body={"image": ["https://example.com/original.png"]},
)

3. Base64 输出

适用于无需下载 URL 即可直接进行程序化处理的场景：

resp = client.images.generate(
    model="agnes-image-2.1-flash",
    prompt="A simple red circle on white background",
    size="512x512",
    return_base64=True,
)
b64_data = resp.data[0].b64_json

重要说明

• response_format 必须置于 extra_body 内部，不可置于请求体顶层
• 图像生成耗时约为 10–60 秒，请将客户端超时时间设为 60–360 秒
• 图生图所用的输入图像必须为公开可访问的 HTTPS URL 或 Data URI
• 请勿添加 tags: ["img2img"] —— 只需提供 image 数组即可
• 当前同时提供 agnes-image-2.1-flash（支持文生图与图生图）和 agnes-image-2.0-flash（专注图生图）两个模型；推荐使用 2.1 版本以统一处理两类任务

配套脚本

scripts/generate.py

命令行图像生成工具：

# 文生图
python scripts/generate.py --prompt "A dragon flying over mountains" --size 1024x768

# 图生图
python scripts/generate.py --prompt "Make it nighttime" --input-image https://example.com/photo.png

# 保存至本地文件
python scripts/generate.py --prompt "Sunset beach" --output sunset.png

自动从环境变量读取 AGNES_API_KEY。

参考文档

完整参数说明、错误处理机制、提示词工程技巧及更多示例，请参阅 references/api_reference.md。