图片生成 API 文档

通过 HTTP API 调用 GPT Image 2、Nano Banana Pro、Nano Banana 2 和 Nano Banana 2 Lite 图片生成服务，兼容 OpenAI 图片接口格式。

🔑 认证方式

在网站登录后，点击顶栏 API 按钮创建 API Key。所有 API 请求需要在 Header 中携带：

Authorization: Bearer sk-your-api-key

📋 模型列表

返回 OpenAI 兼容格式的可用模型列表，可用于客户端自动发现模型 ID。

curl https://image2free.com/v1/models

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "created": 1764547200,
      "owned_by": "image2free"
    }
  ]
}

🎨 生成图片

请求参数 (JSON Body)

支持的图片模型

请求示例

curl -X POST https://image2free.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴着宇航员头盔的猫咪，在月球上弹吉他，赛博朋克风格",
    "size": "16:9",
    "quality": "hd",
    "output_format": "png",
    "n": 1,
    "image": ["https://example.com/cat.png"]
  }'

curl -X POST https://image2free.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview-4k",
    "prompt": "Create a cinematic product photo of a glass perfume bottle on black marble",
    "size": "16:9",
	    "async": true,
    "n": 1
  }'

curl -X POST https://image2free.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "快速生成一张干净的产品海报，白色背景，高级光影",
    "size": "1:1",
    "quality": "standard",
    "image": ["https://example.com/reference.png"]
  }'

响应示例

同步模式（默认）会在图片生成完成后返回：

{
  "created": 1714000000,
  "data": [
    {
      "url": "https://image2free.com/api/jobs/abc123/image"
    }
  ]
}

异步模式传入 "async": true，接口立即返回：

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "j_abc123"
    }
  ]
}

✏️ 编辑图片

基于已有图片进行编辑、风格迁移或局部修改（mask）。兼容 OpenAI /v1/images/edits 接口，支持 OpenAI SDK 的 client.images.edit() 调用。

请求参数 (multipart/form-data)

请求示例

curl -X POST https://image2free.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "prompt=Put a crown on the cat's head" \
  -F "image=@cat.png" \
  -F "model=gpt-image-2" \
  -F "output_format=png" \
  -F "async=true"

# 使用 mask 局部编辑
curl -X POST https://image2free.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "prompt=Replace the background with a sunset beach" \
  -F "image=@photo.png" \
  -F "mask=@mask.png" \
  -F "model=gpt-image-2"

响应格式

同步和异步响应格式均与 /v1/images/generations 一致。

🖼️ 获取图片

通过 job ID 获取已完成任务的图片 URL。任务尚未完成时返回 409 not_ready，生成失败返回 422 generation_failed，文件已过期或被删除返回 410 gone。查询任务进度和失败原因请使用 /v1/tasks/{id}。

🎬 生成视频

提交 Seedance 2.0、VEO3.1 或 HappyHorse 1.0 视频任务，接口异步返回任务 ID，再用 /v1/tasks/{id} 查询结果。HappyHorse 1.0 当前按 720p = 22 积分/秒、1080p = 38 积分/秒 计费。

curl -X POST https://image2free.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0-fast",
    "prompt": "城市夜景延时摄影，镜头缓慢推进",
    "resolution": "720p",
    "size": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

curl -X POST https://image2free.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "海豚在碧蓝海洋中跳跃",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 8
  }'

curl -X POST https://image2free.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happyhorse-1.0",
    "prompt": "A little girl walking down the road, cinematic feel",
    "resolution": "1080P",
    "size": "16:9",
    "duration": 5,
    "seed": 42
  }'

🎞️ VEO3 视频续写

续写已完成的 VEO3 视频。路径里的 task_id 是本站返回的任务 ID，模型必须与原视频一致。

curl -X POST https://image2free.com/v1/videos/job-id/remix \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "猫咪继续在草地上奔跑，蝴蝶飞向远方",
    "raw": false,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

⏱️ 查询任务

查询图片或视频异步任务。状态可能为 queued、running、done 或 error。

curl https://image2free.com/v1/tasks/job-id \
  -H "Authorization: Bearer sk-your-api-key"

{
  "code": 200,
  "data": {
    "id": "j_abc123",
    "status": "done",
    "progress": 100,
    "output_available": true,
    "result": {
      "images": [
        {"url": ["https://image2free.com/api/jobs/j_abc123/image"]}
      ]
    }
  }
  }

任务失败时接口仍返回 HTTP 200，任务状态和失败原因位于 data：

{
  "code": 200,
  "data": {
    "id": "j_abc123",
    "status": "error",
    "progress": 0,
    "output_available": false,
    "error": {
      "message": "生成超时，请重试",
      "type": "generation_failed"
    }
  }
}

👤 查询积分

curl https://image2free.com/v1/me \
  -H "Authorization: Bearer sk-your-api-key"

{
  "id": "user-id",
  "email": "you@example.com",
  "balance": 42
}

⚠️ 错误处理

错误响应格式（兼容 OpenAI）：

{
  "error": {
    "message": "Insufficient credits.",
    "type": "insufficient_quota",
    "code": 402
  }
}

💻 代码示例

Python

import requests

resp = requests.post(
    "https://image2free.com/v1/images/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={"model": "gpt-image-2", "prompt": "一只可爱的柴犬在樱花树下", "size": "1024x1024"}
)

# 带参考图片的编辑请求
resp = requests.post(
    "https://image2free.com/v1/images/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "nano-banana-2-lite",
        "prompt": "把这只狗变成水彩画风格",
        "image": ["https://example.com/dog.png"]
    }
)
data = resp.json()["data"][0]

# 下载图片
img = requests.get(data["url"]).content
with open("output.png", "wb") as f:
    f.write(img)
print("Saved to output.png")

JavaScript / Node.js

const resp = await fetch("https://image2free.com/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-your-api-key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "nano-banana-2-lite",
    prompt: "A cat wearing an astronaut helmet on the moon",
    size: "1024x1024",
    quality: "hd",
    // image: ["https://example.com/cat.png"]  // 可选：参考图片
  })
});
const { data } = await resp.json();
console.log("Image URL:", data[0].url);

兼容 OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://image2free.com/v1"
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="赛博朋克城市夜景，霓虹灯",
    size="1024x1024",
    n=1
)
print(result.data[0].url)

OpenAI SDK 编辑图片

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://image2free.com/v1"
)

# 使用参考图编辑
result = client.images.edit(
    model="gpt-image-2",
    image=[open("cat.png", "rb")],
    prompt="Put a crown on the cat's head"
)
print(result.data[0].url)

# 使用 mask 局部编辑
result = client.images.edit(
    model="gpt-image-2",
    image=[open("photo.png", "rb")],
    mask=open("mask.png", "rb"),
    prompt="Replace the background with a sunset beach"
)
print(result.data[0].url)

📋 限制说明

• 每次请求生成 1 张图片；GPT Image 2 按画质扣费：1K = 1 积分／2K = 2 积分／4K = 3 积分；Nano Banana Pro 固定 10 积分，Nano Banana 2 固定 5 积分，Nano Banana 2 Lite 仅支持 1K、1 积分
• 任务失败自动退回对应积分
• 图片生成和编辑默认同步返回；传入 async=true 可立即获取任务 ID，并通过 /v1/tasks/{id} 轮询
• 每用户默认最多 5 个并发任务（不论几个 API Key），可申请提高
• 支持 1K / 2K / 4K 分辨率（4K 为实验性，仅支持部分比例；Nano Banana 2 Lite 仅支持 1K）
• 支持上传参考图片（image 或 image_urls），最多 5 张，用于图片编辑/风格迁移
• /v1/images/edits 端点支持 multipart/form-data 上传本地图片和 mask，兼容 OpenAI SDK 的 client.images.edit()
• 每用户最多 5 个 API Key
• API Key 只在创建成功时完整显示一次，服务端仅保存不可逆指纹；请在创建后立即妥善保存
• 生成的图片保留 12 小时，请及时下载
• API 接口兼容 OpenAI SDK，可直接替换 base_url 使用