SukidataSukidata

AI

图片生成与编辑

使用 GPT Image 2.5 和 GPT Image 2，通过文字提示词与参考图生成和编辑图片。

打开 Playground API 参考

生成图片

向 POST /v1/images/generations 发送提示词。以下示例使用 gpt-image-2.5，返回可直接下载的图片 URL。

cURL
curl --request POST \
  --url https://api.sukidata.com/v1/images/generations \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-example-001' \
  --data '{
    "model": "gpt-image-2.5",
    "prompt": "A blue ceramic cup on a plain white background",
    "response_format": "url"
  }'
响应
{
  "created": 1788739200,
  "data": [{ "url": "https://example.com/result.png" }]
}

从 data[0].url 获取图片。省略 response_format 时，图片以 Base64 返回在 data[0].b64_json 中。

调用前请准备 API Key 和足够的 AI 余额。每个新任务使用新的 Idempotency-Key，重试时复用原键。

编辑图片

向 POST /v1/images/edits 提交图片，并在提示词中描述需要修改的内容。

上传文件

cURL · multipart/form-data
curl --request POST \
  --url https://api.sukidata.com/v1/images/edits \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Idempotency-Key: image-edit-example-001' \
  --form 'model=gpt-image-2.5' \
  --form 'prompt=Change the cup to green, keeping the composition' \
  --form 'image=@input.png'

多张图片使用多个 --form 'image[]=@file.png'，每个字段对应一个文件。输入支持 PNG、JPEG 和 WebP。

使用图片 URL

cURL · application/json
curl --request POST \
  --url https://api.sukidata.com/v1/images/edits \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-json-edit-example-001' \
  --data '{
    "model": "gpt-image-2.5",
    "prompt": "Replace the background with a snowy mountain",
    "image": {"image_url": "https://example.com/input.png"},
    "mask": {"image_url": "https://example.com/mask.png"},
    "output_format": "webp"
  }'

使用公开 HTTPS 图片 URL 或 Base64 data URL。JSON 字段从 image 和 images 中选择一个，两者均支持单张参考图和数组。

可选的 mask 须为带 alpha 通道的 PNG，尺寸与第一张参考图一致，透明区域表示需要编辑的位置。

请求体最大 48 MiB，参考图数量上限由所选模型决定。

调整输出

modelgpt-image-2.5 或 gpt-image-2，均支持以下参数。
size可用 auto 或具体尺寸，例如 1024x1024、1536x1024。宽高最大 3840，宽高比介于 1:3 和 3:1，总像素介于 655,360 和 8,294,400。
quality可选 auto、low、medium、high。
n输出图片数量，生成和编辑每次均支持 1–4 张，默认 1 张。
output_format可选 png、jpeg、webp。JPEG 和 WebP 可配合 output_compression（0–100）调整压缩。
background可选 auto、opaque、transparent。透明背景须使用 PNG 或 WebP。

通过 GET /v1/models 查询可用模型。完整字段见 API 参考，尺寸档位与 1K 预设价格见计费说明。

异步生成

使用 POST /v1/images/generations/async，提交后即可获取任务 ID。异步编辑使用 POST /v1/images/edits/async，参数分别与对应的同步接口相同。

1 · 提交任务
curl --request POST \
  --url https://api.sukidata.com/v1/images/generations/async \
  --header "Authorization: Bearer $SUKIDATA_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: image-async-example-001' \
  --data '{"model":"gpt-image-2.5","prompt":"A blue ceramic cup"}'
202 Accepted
{
  "id": "img_example",
  "object": "image.task",
  "status": "queued"
}
2 · 查询进度
curl https://api.sukidata.com/v1/images/tasks/img_example \
  --header "Authorization: Bearer $SUKIDATA_API_KEY"
queued排队中，等待几秒后再次查询。
processing生成中，等待几秒后再次查询。
completed已完成，从 images[].url 下载图片。
failed已失败，通过 error 查看原因。
unknown结果尚未确认，请继续查询同一个任务 ID。

提交响应的 Location 头也会返回任务查询地址。查询时使用同一 Workspace 的 API Key。

Python 示例

安装 OpenAI Python SDK 后，设置 Sukidata 的 API Key 和接口地址：

Python
import os
import uuid
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SUKIDATA_API_KEY"],
    base_url="https://api.sukidata.com/v1",
    timeout=120.0,
    max_retries=2,
)

request_key = str(uuid.uuid4())
result = client.images.generate(
    model="gpt-image-2.5",
    prompt="A blue ceramic cup on a plain white background",
    extra_headers={"Idempotency-Key": request_key},
)
image_base64 = result.data[0].b64_json

查找与保存结果

GET /v1/images/tasks 列出当前 Workspace 的任务，可按模型、状态或提示词筛选。通过 GET /v1/images/tasks/{task_id} 查看单个任务的提示词、参数、图片和费用。

图片 URL 自发布起可用 31 天。请在 url_expires_at 之前保存文件，到期后无法通过 API 下载。持有 URL 的人均可打开图片，请谨慎分享链接。

错误与重试

超时或连接断开不会取消任务。如果响应中包含 X-Sukidata-Task-ID，请先查询该任务，再决定是否重新提交。

未收到任务 ID 时，使用相同的 Idempotency-Key、参数和文件重试。更换键会创建新任务，可能产生另一笔费用。输入上传中断后，可在任务创建后的十分钟内重试。

  • 400：检查模型、输入文件和参数取值。
  • 402：充值 AI 余额。
  • 409：该幂等键已用于不同的参数或文件。
  • 410：上传重试窗口或图片链接已到期。
  • 502 / 503：先查询原任务，它可能仍在处理中。

其他错误可查看响应中的 error.code 和 error.message。联系技术支持时，请附上任务 ID 或 X-Request-ID。