图片 / 视频生成 API 文档

通过 HTTP API 调用图片和视频生成服务。图片接口兼容 OpenAI SDK；视频接口为异步任务接口。

🔑 认证方式

在网站登录后，点击顶栏 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"
    }
  ]
}

模型能力速查

图片接口用 size 传比例或像素尺寸，用 quality 传分辨率档位。视频接口用 aspect_ratio 或 size 传比例，用 resolution 传清晰度。

图片模型

视频模型

🎨 生成图片

请求参数 (JSON Body)

传 size 时先查模型能力表。示例：GPT Image 2 可传 1350x900；Nano Banana 2 Lite 应传 16:9 或 auto，不要传 1024x1024。

请求示例

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",
	    "n": 1,
	    "image_urls": ["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",
	    "prompt": "Create a cinematic product photo of a glass perfume bottle on black marble",
	    "size": "16:9",
	    "quality": "uhd",
	    "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_urls": ["https://example.com/reference.png"]
	  }'

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": "A cute cartoon orange cat sticker, thick white outline, flat vector style",
    "size": "1:1",
    "quality": "standard",
    "background": "transparent",
    "output_format": "png"
  }'

# 局部重绘：只把遮罩透明区域重新生成（把天空换成日落）\
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": "Turn the masked area into a warm desert sunset",
    "size": "1:1",
    "quality": "standard",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'

响应示例

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

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

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

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

✏️ 编辑图片

基于已有图片进行编辑、风格迁移。兼容 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 "async=true"

# 参考图编辑
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 "model=nano-banana-2-lite" \
  -F "size=1:1" \
  -F "quality=standard"

# 局部重绘：只有 mask 的透明区域会被重新生成
curl -X POST https://image2free.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "prompt=Turn the masked area into a warm desert sunset" \
  -F "image=@photo.png" \
  -F "mask=@mask.png" \
  -F "model=gpt-image-2" \
  -F "size=1:1"

响应格式

同步和异步响应格式均与 /v1/images/generations 一致；response_format=b64_json 时返回 data[0].b64_json。

🤖 OpenAI 标准格式支持

图片接口按 OpenAI 官方请求格式实现，可直接使用 OpenAI 官方 SDK / 客户端（把 base_url 指向 https://image2free.com/v1 即可）。下面逐项列出支持情况，避免参数被静默忽略。

字段支持一览

本服务扩展字段（非 OpenAI 标准）

• image_urls：生成接口用 URL 传参考图，免去 multipart
• mask_url：生成接口用 URL 传遮罩
• async：立即返回任务 ID，异步取图

Python SDK 示例

from openai import OpenAI

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

# 透明贴纸（1K）
sticker = client.images.generate(
    model="gpt-image-2",
    prompt="A cute cartoon cat sticker, flat vector style",
    size="1:1",
    quality="high",
    background="transparent",
    output_format="png",
    response_format="b64_json",
)

# 局部重绘：mask 的透明区域会被重新生成
edited = client.images.edit(
    model="gpt-image-2",
    image=open("photo.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="Replace the masked area with a warm sunset",
    size="1:1",
)

🖼️ 获取图片

通过 job ID 获取已完成任务的图片 URL。需要直接下载文件时请求 GET /v1/images/{id}/content，接口会跳转到图片文件。任务尚未完成时返回 409 not_ready，生成失败返回 422 generation_failed，文件已过期或被删除返回 410 gone。查询任务进度和失败原因请使用 /v1/tasks/{id}。

🎬 视频接口

异步提交视频任务，接口立即返回 task_id，再用 GET /v1/tasks/{id} 轮询结果。当前视频单价为限时特价（标价 × 0.7）。

请求参数 (JSON Body)

注意：首帧/尾帧字段与参考素材（image_urls / video_urls / audio_urls / reference_image）互斥，混用会返回 400。VEO Lite 不接受参考图；音频参考不能单独传。

文生视频示例

curl https://image2free.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "一个男孩在海边打篮球，黄昏，海浪拍岸，电影感运镜",
    "duration": 5,
    "resolution": "2k",
    "aspect_ratio": "16:9"
  }'

图生视频示例

curl 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": "720p",
    "aspect_ratio": "16:9",
    "image_urls": ["https://example.com/frame.png"],
    "generation_type": "reference"
  }'

多模态参考示例

curl https://image2free.com/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3",
    "prompt": "参考人物服装和音乐节奏，生成一段街舞短片",
    "duration": 6,
    "resolution": "2k",
    "aspect_ratio": "9:16",
    "image_with_roles": [
      {"url": "https://example.com/person.png", "role": "reference_image"}
    ],
    "audio_urls": ["https://example.com/music.mp3"]
  }'

Remix 示例

curl https://image2free.com/v1/videos/task-id/remix \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "prompt": "保持主体动作，改成雨夜霓虹街道风格",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

提交响应

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

用 GET /v1/tasks/{task_id} 查询进度与结果；成功后输出视频 URL，失败自动退款。

获取视频文件

⏱️ 查询任务

查询图片/视频异步任务。状态可能为 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": "把这只狗变成水彩画风格",
	        "size": "1:1",
	        "quality": "standard",
	        "image_urls": ["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: "1:1",
	    quality: "standard",
	    image_urls: ["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("photo.png", "rb")],
    prompt="Replace the background with a sunset beach"
)
print(result.data[0].url)

📋 限制说明

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