WellAPI gpt-image-2#

Generate and edit images via the WellAPI gpt-image-2 model (OpenAI-compatible). The API returns image bytes inline as base64 ( data[i].b64_json) — no polling, no URL download.

API Endpoints#

• Base: https://wellapi.ai/v1
• Text-to-image: POST /images/generations — application/json
• Image edit / image-to-image: POST /images/edits — multipart/form-data

Authentication: Authorization: Bearer <WELLAPI_API_KEY> header.

Request — /images/generations (text-to-image)#

Content-Type: application/json

FieldTypeRequiredNotesmodelstring✅e.g. gpt-image-2``promptstring✅Image description, max 1000 charsninteger✅Number of images, 1–10sizestringoptionalSee size table below; default auto``qualitystringoptionallow / medium / high / auto (default auto)formatstringoptionalpng / jpeg / webp (default png)

Example body:

json

{
  "model": "gpt-image-2",
  "prompt": "大海",
  "n": 1,
  "size": "1024x1024",
  "quality": "low",
  "format": "jpeg"
}

Request — /images/edits (image-to-image / editing)#

Content-Type: multipart/form-data

FieldTypeRequiredNotesimagefile (repeatable)✅One or more input images. Up to 16 images, total ≤ 50MB.promptstring✅Edit descriptionmaskfileoptionalA PNG with fully transparent regions marking the edit area. Applied to the first image if multiple are sent. Must be valid PNG, < 4MB, same dimensions as the image.modelstringoptionalgpt-image-1, gpt-image-1-all, flux-kontext-pro, flux-kontext-max, gpt-image-2, gpt-image-2-all. Default in this skill: gpt-image-2.nstringoptional"1" – "10"``sizestringoptionalSee size tablequalitystringoptionallow / medium / high / auto (default auto)formatstringoptionalpng / jpeg / webp``backgroundstringoptionalopaque / auto / transparent. auto lets the model pick.moderationstringoptionallow / auto (default). low = less restrictive filtering (gpt-image-1 family).

size values#

ValueDescription1024x1024Square1536x1024Landscape1024x1536Portrait2048x20482K square2048x11522K landscape3840x21604K landscape2160x38404K portraitautoDefault — model chooses

Strict size rules (when picking a custom size):

1. Longest side ≤ 3840px
2. Both width and height must be multiples of 16
3. max(w, h) / min(w, h) ≤ 3:1
4. Total pixels: 655,360 ≤ w*h ≤ 8,294,400

Response (both endpoints)#

Synchronous JSON — no polling:

json

{
  "created": 1778236581,
  "background": "opaque",
  "data": [
    { "b64_json": "iVBORw0KGgo..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 8,
    "input_tokens_details": { "image_tokens": 0, "text_tokens": 8 },
    "output_tokens": 196,
    "total_tokens": 204
  }
}

Each data[i].b64_json is the full image as a base64 string. Decode and write to disk.

Output#

1. Base64-decode each data[i].b64_json into bytes.
2. Save as wellapi-<TIMESTAMP>.<ext> where <ext> matches response.output_format (or the requested format, fallback png).
3. If multiple images returned, append -1, -2, … to the filename.
4. Print MEDIA:<absolute_path> (one line per image) for OpenClaw auto-attach.

CRITICAL SECURITY: Before passing an output filename to shell commands, sanitize:

• Strip shell metacharacters: tr -cd 'A-Za-z0-9._-'
• Enforce valid extension ( .png, .jpg, .jpeg, .webp)
• Fallback to wellapi-<timestamp>.png if empty

Reference Implementations#

PlatformFilePython (all platforms, zero deps){baseDir}/references/python.mdPowerShell 5.1+ (Windows){baseDir}/references/powershell.mdcurl + bash (Unix/macOS){baseDir}/references/curl_heredoc.md

API Key#

• WELLAPI_API_KEY env var (required) — sent as Authorization: Bearer <key>
• Get key: https://wellapi.ai
• If the environment variable is unset, follow First-run onboarding below.

First-run onboarding (no API key found)#

When no key can be located (env var unset, no cached key on disk), before making any API call show the user this short prompt verbatim. Translate to the user's language if appropriate. Do not expand it into multiple "options / methods", do not show shell commands, do not ask follow-up questions like "do you already have a key":

请粘贴你的 WellAPI API Key。 如果还没有，请前往 https://wellapi.ai/register?channel=c_qqn3vdvc 注册后领取免费 API Key。

Please paste your WellAPI API Key. If you don't have one yet, register at https://wellapi.ai/register?channel=c_qqn3vdvc to get a free key.

After the user pastes a key, use it for the current request and proceed straight to image generation. Do not lecture the user about env vars, shells, or persistence unless they explicitly ask how to save it.

Triggers#

• Chinese: "高质量生图：xxx" / "编辑图片：xxx"
• English: "best image: xxx" / "edit image: xxx"

Treat the text after the colon as prompt, default size=auto, quality=auto, format=png, n=1, and generate immediately.

For image editing, the user provides one or more local image file paths along with the prompt; submit them as repeated image form fields to /images/edits.

Notes#

• Response is synchronous — no task ID, no polling.
• Print MEDIA:<absolute_path> for OC auto-attach — one line per generated image.
• quality: high and larger size values may incur extra charges.
• format controls the encoding of the returned base64 bytes; the file extension should match.
• Up to 16 reference images per edit request, total ≤ 50MB.
• mask requires PNG ≤ 4MB, same WxH as the image it applies to.