Generate and edit images

Use gpt-image-2 with the Images API. Create a global API key, add USD credit, and set BEEFAPI_KEY as described in Quickstart.

Generate an image

curl --fail-with-body https://global.beefapi.com/v1/images/generations \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A small orange sailboat on a quiet lake, watercolor illustration",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }' -o image-response.json

This call waits for the image. Allow several minutes in your HTTP client; a client timeout does not prove generation stopped. Do not automatically submit the same image again after an ambiguous timeout.

A successful response contains created and data. Each item has b64_json or url, depending on the requested response format and model route. Save the base64 result with Python 3:

import base64
import json
from pathlib import Path

response = json.loads(Path("image-response.json").read_text())
Path("image.png").write_bytes(base64.b64decode(response["data"][0]["b64_json"]))

With "response_format": "url", read data[0].url and download it promptly. Treat result URLs as private, potentially expiring links, not permanent hosting.

Edit a local image

Put source.png in your current directory. Send a multipart request; curl supplies the boundary automatically:

curl --fail-with-body https://global.beefapi.com/v1/images/edits \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Make the sailboat blue, preserving the composition and watercolor style' \
  -F 'image=@source.png' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -o image-response.json

Save the returned image using the same Python snippet. Start with PNG or JPEG input. Only upload images you have permission to use.

You can also send JSON with image set to a publicly accessible HTTPS image URL or a complete data:image/png;base64,... URL. Replace the example URL with your own image:

{
  "model": "gpt-image-2",
  "prompt": "Make the sailboat blue",
  "image": "https://example.com/source.png",
  "n": 1,
  "response_format": "b64_json"
}

Parameters

Support for custom dimensions, masks, transparent backgrounds, and output formats varies by route. An accepted optional field does not guarantee that every model honors it. Keep the initial request minimal, inspect the returned image, and include the request ID when asking support about a specific option.

Optional asynchronous image jobs

Some accounts have access to image jobs. They are not available on every route that serves gpt-image-2; use the synchronous examples above unless your account supports them.

Poll every few seconds with the same API key. Stop on completed or failed. Fetching a result before completion returns 409; a failed job includes an error. An unsupported job submission returns an error rather than silently becoming a synchronous request. After a definitive unsupported-route error, use the synchronous endpoint.

Cost and failures

Image models labeled per image on Pricing charge for generated images. Read the current USD amount from pricing.usd.json; do not infer it from text-token prices.

Check Usage after completion. For failures, keep the HTTP status, error body, request ID, and any job ID. See Billing for reserved credit and Errors for retry guidance.