GPT Image 2 API 文档

通过 HTTP API 调用 GPT Image 2 图片生成服务，兼容 OpenAI 格式。

🔑 认证方式

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

Authorization: Bearer sk-your-api-key

🎨 生成图片

POST /v1/images/generations

请求参数 (JSON Body)

参数	类型	必填	说明
prompt	string	✅	图片描述（支持中英文）
size	string	否	尺寸或比例（默认 1024x1024）。支持像素格式如 1024x1024，或比例格式如 1:1/16:9/9:16/4:3/3:4/3:2/2:3/21:9/2:1 等，也支持 auto。具体像素输出分辨率由 quality 控制
quality	string	否	standard（1K，默认，1 积分），hd（2K，2 积分），uhd（4K，3 积分，仅支持 16:9/9:16/2:1/1:2/21:9/9:21）
model	string	✅	模型 ID，固定为 gpt-image-2。
image_urls	string[]	否	参考图片，最多 5 张。支持 HTTP URL 或 data URL（data:image/png;base64,...）。用于图片编辑/风格迁移
n	int	否	固定为 1，每次生成 1 张图片

请求示例

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"]
  }'

响应示例

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

🖼️ 获取图片

GET /v1/images/{id}

通过 job ID 获取生成的图片（base64 + URL）。

🎬 生成视频

POST /v1/videos/generations

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

参数	类型	必填	说明
model	string	否	支持 doubao-seedance-2.0*、veo3.1-fast、veo3.1-quality、veo3.1-lite、happyhorse-1.0
prompt	string	通常必填	除 HappyHorse 的 first_frame_image 模式外，视频描述必填
resolution	string	否	Seedance 支持 480p/720p；VEO3 支持 720p/1080p/4k；HappyHorse 支持 720p/1080p
duration	int	否	Seedance 为 4-15 秒，按秒扣费；VEO3 固定 8 秒，按次扣费；HappyHorse 为 3-15 秒，按秒扣费，编辑模式按源视频时长计费
size / aspect_ratio	string	否	VEO3 支持 16:9/9:16；Seedance 另支持方形、4:3、21:9、adaptive；HappyHorse 支持 16:9/9:16/1:1/4:3/3:4
first_frame_image / video_url	string	否	HappyHorse 专用：first_frame_image 走 I2V；video_url 走 EDIT
audio_setting / watermark	mixed	否	HappyHorse 编辑模式支持 audio_setting: auto/origin；HappyHorse 支持 watermark
generation_type / enable_gif / official_fallback	mixed	否	VEO3 专用：generation_type 支持 frame/reference；enable_gif 仅支持 720p；official_fallback 不支持 lite
image_urls / video_urls / audio_urls	string[]	否	公网可访问的参考素材 URL。VEO3 图片最多 3 张；HappyHorse 的编辑模式中建议使用 video_url 而不是 video_urls

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 视频续写

POST /v1/videos/{task_id}/remix

续写已完成的 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"
  }'

⏱️ 查询任务

GET /v1/tasks/{id}

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

👤 查询余额

GET /v1/me

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

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

⚠️ 错误处理

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

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

HTTP Code	Type	说明
401	unauthorized	API Key 无效或缺失
402	insufficient_quota	积分不足
429	rate_limit_exceeded	请求过于频繁
500	server_error	服务端错误

💻 代码示例

Python

import requests, base64

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

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

# 保存图片
img_bytes = base64.b64decode(data["b64_json"])
with open("output.png", "wb") as f:
    f.write(img_bytes)
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({
    prompt: "A cat wearing an astronaut helmet on the moon",
    size: "1024x1024",
    // 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(
    prompt="赛博朋克城市夜景，霓虹灯",
    size="1024x1024",
    n=1
)
print(result.data[0].url)

📋 限制说明

每次请求生成 1 张图片，按画质扣费：标清 1K = 1 积分／高清 2K = 2 积分／超清 4K = 3 积分
任务失败自动退回对应积分
每用户默认最多 2 个并发任务（不论几个 API Key），可申请提高
支持 1K / 2K / 4K 分辨率（4K 为实验性，仅支持部分比例）
支持上传参考图片（image_urls），最多 5 张，用于图片编辑/风格迁移
每用户最多 5 个 API Key
生成的图片保留 12 小时，请及时下载
API 接口兼容 OpenAI SDK，可直接替换 base_url 使用