Notion API image block with a Sume URL: PNG works, WebP is not listed

Request png or jpeg from Sume, then append an image block with type: "external". Notion's block reference lists the file types it supports for external image URLs: .bmp, .gif, .heic, .jpeg, .jpg, .png, .svg, .tif and .tiff. WebP is not in that list, and WebP is something Sume's image API can return, so choose the format yourself.

The page adds two rules about the URL: the image must be directly hosted, and the URL cannot point to a service that retrieves the image. It must also be publicly accessible. A Sume data[0].url is a hosted file link that ends in the file extension, which matches that description.

What is the block JSON?

This is the shape from Notion's page. Send it as an element of the children array when you append blocks to a page.

{
  "type": "image",
  "image": {
    "type": "external",
    "external": {
      "url": "https://media.sume.com/img/EXAMPLE/0.png"
    }
  }
}

Which Sume request goes with it?

A body that produces a file Notion accepts:

{
  "model": "openai/gpt-image-2.5",
  "prompt": "isometric illustration of a tidy desk, soft colors, no text",
  "quality": "medium",
  "output_format": "png"
}

Where does this go wrong?

Recraft V4 lists webp as its only output format in the Sume catalog, so it is the wrong model for a Notion page; the other catalog models list png, jpeg and webp. Reading the data[].media_type field in the response tells you what you got before you build the block.

A 202 means the job outlived the 30-second wait, and the response has no image yet. Poll status_url and read result_url, as the jobs guide says, before you create the block. Do not send the generation request again.

Because Notion needs a public URL, anyone who has the link can open the image. Keep unreleased product art out of a page whose blocks point to public links, and check usage.cost on each 200 response if you generate a whole page of illustrations.

For captions, Notion's image block can carry text of its own, so put the description there and not in the image. Keep the prompt and the Sume model id in a property on the page, so the next editor knows how the picture was made and can ask for a variant in the same style without starting from nothing.