LogoJoyAI Image

JoyAI Image API

API 文档

通过一个公开 API 接口生成和编辑图片。使用 joyai 进行基于指令的图片编辑，或使用 gptimage2 进行 GPT Image 2 文生图与图片编辑。

管理 API 密钥快速开始

概览

端点

/api/v1/generate

一个端点支持所有图片模型，通过 model 字段选择行为。

认证

Bearer API 密钥

在 Authorization 请求头中使用控制台 API 密钥。服务端密钥不会发送到浏览器。

异步

基于任务的结果

生成接口返回 task ID，轮询状态端点获取最终图片 URL。

身份认证

每个请求都需要在 Authorization 请求头中携带 API 密钥。在以下位置创建或轮换密钥： 控制台 > API 密钥.

请求头
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

模型与积分

model适用场景是否需要图片输入积分
joyai基于指令的图片编辑，支持 1 至 3 张参考图。是，需要 1 至 3 个图片 URL。每次请求 24 积分。
gptimage2GPT Image 2 文生图与图片编辑。可选。提供图片时进入编辑模式。文生图：低/中/高分别为 1k/2k/4k 的 2/4/6、12/24/36、44/88/132 积分。编辑：低/中/高分别为 1k/2k/4k 的 6/12/18、12/24/36、44/88/132 积分。

快速开始

向 POST /api/v1/generate. 发送请求。API 会立即返回 task ID；使用 GET /api/v1/status 轮询直到任务成功或失败。

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

创建图片生成或编辑任务。请求体为 JSON。

请求参数

名称类型必填说明
modelstring是使用 joyai 或 gptimage2。
promptstring是自然语言指令。joyai 最多 1500 字符；gptimage2 最多 20000 字符。
imagesstring[]joyai 必填；gptimage2 可选图片 URL。joyai 接受 1 至 3 张图片；gptimage2 提供图片时进入编辑模式。
sizestringjoyai 可选输出尺寸，如 1024*1024。默认 1024*1024。
qualitystringgptimage2 可选low、medium 或 high。默认 medium。
resolutionstringgptimage2 可选1k、2k 或 4k。默认 1k。
aspect_ratiostringgptimage2 可选1:1、3:2、2:3、3:4、4:3、4:5、5:4、9:16、16:9 或 21:9。
output_formatstringgptimage2 可选png、jpeg 或 webp。默认 png。
callback_urlstring可选可与任务一起存储的 URL，用于下游回调流程。

JoyAI 编辑示例

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

GPT Image 2 示例

cURL
curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

响应

JSON
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

使用 /api/v1/generate. 返回的 task ID 轮询任务状态。model 参数可选；在可能的情况下会自动路由 task ID。

cURL
curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

错误

错误响应与成功响应使用相同结构。公开响应不会暴露内部供应商名称、Worker 名称或路由细节。

JSON
{
  "code": 400,
  "message": "prompt is required",
  "data": null
}
状态码含义
400缺少或无效的请求参数。
401缺少或无效的 API 密钥。
402积分不足。
500生成服务或服务器错误。若重复出现请联系支持。