GitHub social preview as a transparent PNG: which Sume model

GitHub accepts a PNG, JPG or GIF social preview under 1 MB, and says that, because many platforms have a dark mode, a transparent social preview may be beneficial. On Sume the way to get real alpha is ChatGPT Image 2.5 (openai/gpt-image-2.5) with background: "transparent". Its aspect_ratio list has no 2:1, so this post generates 16:9 and places the artwork on a transparent 1280 x 640 canvas yourself.

What GitHub states

The documentation sentence is: your image should be a PNG, JPG or GIF file under 1 MB in size. Beyond that, it recommends at least 640 by 320 pixels, and 1280 by 640 for best display. It also says many platforms support dark mode, so a transparent preview may be beneficial. Both sizes are 2:1.

Which Sume model can give you alpha

The Image API docs state that ChatGPT Image 2.5 takes background: auto|transparent|opaque, and the parameter table marks background as a ChatGPT Image 2.5 feature. A request that sets a parameter the chosen model does not list is rejected with 400 unsupported_parameter, so do not send it to Seedream, FLUX.2, Qwen or Ideogram expecting transparency.

The aspect ratios the catalog lists for the GPT Image family are 1:1, 16:9, 9:16, 4:3, 3:4, 5:4, 9:8, 4:5 and auto. There is no 2:1 in that list. The same docs page says ChatGPT Image 2.5 image_size also accepts custom pixels (edges in multiples of 16, at most 3840, aspect at most 3:1), which would admit 1280 x 640, but the request-parameter table does not list image_size, so confirm it against GET /v1/images/models before relying on it; the composite below works either way. The docs also point to Image 1.0 with transparency: true for transparent stills. FLUX.2 Pro and Flex do list 2:1, but they have no transparency parameter, so they give an opaque card.

Composite onto the 1280 x 640 canvas

The script asks for a 16:9 transparent PNG, shrinks it to fit inside 1280 x 640 while keeping its shape, and centers it on a fully transparent canvas. The side margins stay transparent, so the card reads on both light and dark pages. optimize=True shrinks the PNG losslessly; check the printed size against the 1 MB limit.

import os, io, requests
from PIL import Image
r = requests.post(
    "https://api.sume.com/v1/images",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    json={"model": "openai/gpt-image-2.5", "aspect_ratio": "16:9",
          "background": "transparent", "output_format": "png",
          "prompt": "isometric stack of colorful cubes, no text, no backdrop"},
    timeout=90,
)
r.raise_for_status()
if r.status_code != 200:
    raise SystemExit("202: read the job result before compositing")
art = Image.open(io.BytesIO(requests.get(r.json()["data"][0]["url"], timeout=60).content)).convert("RGBA")
art.thumbnail((1280, 640), Image.LANCZOS)
card = Image.new("RGBA", (1280, 640), (0, 0, 0, 0))
card.alpha_composite(art, ((1280 - art.width) // 2, (640 - art.height) // 2))
card.save("social-preview.png", optimize=True)
print(os.path.getsize("social-preview.png"), "bytes")

Caveats

Transparent art with dark linework disappears on a dark background, and pale art disappears on a light one. Prompt for mid-tone shapes with their own outline or soft shadow, and look at the card on both themes before you upload it. For the plain opaque route and a size check, see the 1280x640 social preview post. ChatGPT Image 2.5 is priced by output tokens, so its per-image cost depends on quality and size; read it from the catalog and the usage.cost field instead of assuming a flat rate.