Generate Image

POST

Generate one or more images from a text prompt using FLUX. Each call consumes 2 credits and returns hosted image URLs that are permanently stored in your gallery.

Endpoint

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

Required scope: graphicoal:generate | Cost: 2 credits per call

Request Parameters

Parameter	Type	Required	Description
prompt	string	required	Text description of the image to generate. Max 2000 characters.
width	integer	optional	Output width in pixels. Range: 256–2048. Default: `1024`.
height	integer	optional	Output height in pixels. Range: 256–2048. Default: `1024`.
num_images	integer	optional	Number of images to generate in a single call. Range: 1–4. Default: `1`.

Request Example

curl -X POST https://coals.ai/api/v1/graphicoal/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A photorealistic red fox sitting in a snowy forest, golden hour lighting",
    "width": 1024,
    "height": 1024,
    "num_images": 2
}'

// Using Guzzle
$response = $client->post('https://coals.ai/api/v1/graphicoal/generate', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'json' => [
    "prompt" => "A photorealistic red fox sitting in a snowy forest, golden hour lighting",
    "width" => 1024,
    "height" => 1024,
    "num_images" => 2
]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.post(
  "https://coals.ai/api/v1/graphicoal/generate",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={
    "prompt": "A photorealistic red fox sitting in a snowy forest, golden hour lighting",
    "width": 1024,
    "height": 1024,
    "num_images": 2
}
)
data = response.json()

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

uri = URI("https://coals.ai/api/v1/graphicoal/generate")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
req["Content-Type"] = "application/json"
req.body = '{
    "prompt": "A photorealistic red fox sitting in a snowy forest, golden hour lighting",
    "width": 1024,
    "height": 1024,
    "num_images": 2
}'

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/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "prompt": "A photorealistic red fox sitting in a snowy forest, golden hour lighting",
    "width": 1024,
    "height": 1024,
    "num_images": 2
})
});
const data = await response.json();

Response

{
  "success": true,
  "image_id": "img_01jk8mxp3n4q7r2t6w9",
  "image_url": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
  "width": 1024,
  "height": 1024,
  "generation_time_ms": 3842,
  "credits_charged": 2
}

Response Fields

Field	Type	Description
success	boolean	Always `true` on a successful response.
image_id	string	Unique identifier for the generated image. Use this with gallery endpoints.
image_url	string	Publicly accessible URL to the hosted image (WebP format).
width	integer	Actual output width of the generated image in pixels.
height	integer	Actual output height of the generated image in pixels.
generation_time_ms	integer	Total server-side generation time in milliseconds.
credits_charged	integer	Credits deducted from your balance for this request.

When num_images is greater than 1, the response returns an array of image objects rather than a single object. Each image is independently stored in your gallery and accessible by its own image_id.