Edit Image

POST

Modify an existing image using a text prompt. Provide either a base64-encoded image or a publicly accessible image URL, along with instructions describing the desired change. Each edit consumes 3 credits.

Endpoint

POST https://coals.ai/api/v1/graphicoal/edit

Required scope: graphicoal:edit | Cost: 3 credits per call

Request Parameters

Parameter	Type	Required	Description
prompt	string	required	Instructions describing the desired edits to the image. Max 2000 characters.
image	string	required	The source image as a base64-encoded data URI (e.g. `data:image/png;base64,...`) or a publicly accessible HTTPS URL.
width	integer	optional	Output width for the edited image in pixels. Range: 256–2048. Defaults to source image width.
height	integer	optional	Output height for the edited image in pixels. Range: 256–2048. Defaults to source image height.

Request Example

curl -X POST https://coals.ai/api/v1/graphicoal/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the background to a sunset over the ocean, keep the subject unchanged",
    "image": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
    "width": 1024,
    "height": 1024
}'

// Using Guzzle
$response = $client->post('https://coals.ai/api/v1/graphicoal/edit', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'json' => [
    "prompt" => "Change the background to a sunset over the ocean, keep the subject unchanged",
    "image" => "https =>//coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
    "width" => 1024,
    "height" => 1024
]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.post(
  "https://coals.ai/api/v1/graphicoal/edit",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={
    "prompt": "Change the background to a sunset over the ocean, keep the subject unchanged",
    "image": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
    "width": 1024,
    "height": 1024
}
)
data = response.json()

# Using net/http
require "net/http"
require "json"

uri = URI("https://coals.ai/api/v1/graphicoal/edit")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
req["Content-Type"] = "application/json"
req.body = '{
    "prompt": "Change the background to a sunset over the ocean, keep the subject unchanged",
    "image": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
    "width": 1024,
    "height": 1024
}'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

// Using fetch (Node 18+)
const response = await fetch("https://coals.ai/api/v1/graphicoal/edit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "prompt": "Change the background to a sunset over the ocean, keep the subject unchanged",
    "image": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
    "width": 1024,
    "height": 1024
})
});
const data = await response.json();

To use a local file, encode it as base64 and prefix with the data URI scheme: data:image/png;base64,<base64data>.

Response

{
  "success": true,
  "image_id": "img_01jk9r7vh2n5s8p4m1q",
  "image_url": "https://coals.ai/images/img_01jk9r7vh2n5s8p4m1q.webp",
  "credits_charged": 3
}

Response Fields

Field	Type	Description
success	boolean	Always `true` on a successful response.
image_id	string	Unique identifier for the edited image stored in your gallery.
image_url	string	Publicly accessible URL to the hosted edited image (WebP format).
credits_charged	integer	Credits deducted from your balance for this edit.

The edited image is saved as a new gallery entry with its own image_id. The source image is not modified and remains in your gallery independently.