Gallery Management
All generated, edited, and vectorized images are permanently stored in your gallery. These endpoints let you list, retrieve, delete, and monitor usage of your image library. Gallery reads and deletions do not consume credits.
GET
/images
No credit cost
Return a paginated list of images in your gallery. Filter by operation type or adjust page size using query parameters.
Endpoint
GET https://coals.ai/api/v1/graphicoal/images
Required scope:
graphicoal:read
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| operation | string | optional | Filter by operation type. Accepted values: generate, edit, analyze, svg_generate, svg_convert. Omit to return all types. |
| per_page | integer | optional | Number of results per page. Range: 1–100. Default: 20. |
| page | integer | optional | Page number to retrieve. Default: 1. |
Request Example
curl -G https://coals.ai/api/v1/graphicoal/images \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "operation=generate" \ --data-urlencode "per_page=10"
// Using Guzzle $response = $client->get('https://coals.ai/api/v1/graphicoal/images', [ 'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'], 'query' => [ 'operation' => 'generate', 'per_page' => '10', ] ]); $data = json_decode($response->getBody(), true);
# Using requests import requests response = requests.get( "https://coals.ai/api/v1/graphicoal/images", headers={"Authorization": "Bearer YOUR_API_KEY"}, params={"operation": "generate", "per_page": "10"} ) data = response.json()
# Using net/http require "net/http" require "json" uri = URI("https://coals.ai/api/v1/graphicoal/images") uri.query = URI.encode_www_form({"operation" => "generate", "per_page" => "10"}) req = Net::HTTP::Get.new(uri) req["Authorization"] = "Bearer YOUR_API_KEY" 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/images?operation=generate&per_page=10`, { method: "GET", headers: { "Authorization": "Bearer YOUR_API_KEY" } }); const data = await response.json();
Response
{
"success": true,
"data": [
{
"image_id": "img_01jk8mxp3n4q7r2t6w9",
"image_url": "https://coals.ai/images/img_01jk8mxp3n4q7r2t6w9.webp",
"operation": "generate",
"prompt": "A photorealistic red fox in a snowy forest",
"width": 1024,
"height": 1024,
"created_at": "2026-03-03T14:22:11Z"
}
],
"meta": {
"current_page": 1,
"per_page": 10,
"total": 47,
"last_page": 5
}
}
GET
/images/{id}
No credit cost
Retrieve full details for a single image, including its analysis result (if applicable) and all SVG candidates (for vectorization operations).
Endpoint
GET https://coals.ai/api/v1/graphicoal/images/{id}
Required scope:
graphicoal:read
Response
{
"success": true,
"image_id": "img_01jkbv4xt9w2p6r8n7m",
"image_url": "https://coals.ai/images/img_01jkbv4xt9w2p6r8n7m.webp",
"operation": "svg_generate",
"prompt": "Minimalist geometric mountain range logo",
"width": 1024,
"height": 1024,
"analysis": null,
"svg_candidates": [
{
"preset": "default",
"url": "https://coals.ai/images/img_01jkbv4xt9w2p6r8n7m_default.svg",
"size_bytes": 18432
}
],
"credits_charged": 3,
"created_at": "2026-03-03T15:04:29Z"
}
The analysis field contains the text result for /analyze operations, and null for all other types. svg_candidates is populated only for SVG operations.
DELETE
/images/{id}
No credit cost
Permanently delete an image and all associated files (including SVG candidates) from your gallery. This action is irreversible.
Endpoint
DELETE https://coals.ai/api/v1/graphicoal/images/{id}
Required scope:
graphicoal:delete
Request Example
curl -X DELETE https://coals.ai/api/v1/graphicoal/images/img_01jk8mxp3n4q7r2t6w9 \ -H "Authorization: Bearer YOUR_API_KEY"
// Using Guzzle $response = $client->delete('https://coals.ai/api/v1/graphicoal/images/img_01jk8mxp3n4q7r2t6w9', [ 'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'] ]); $data = json_decode($response->getBody(), true);
# Using requests import requests response = requests.delete( "https://coals.ai/api/v1/graphicoal/images/img_01jk8mxp3n4q7r2t6w9", headers={"Authorization": "Bearer YOUR_API_KEY"} ) data = response.json()
# Using net/http require "net/http" require "json" uri = URI("https://coals.ai/api/v1/graphicoal/images/img_01jk8mxp3n4q7r2t6w9") req = Net::HTTP::Delete.new(uri) req["Authorization"] = "Bearer YOUR_API_KEY" 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/images/img_01jk8mxp3n4q7r2t6w9", { method: "DELETE", headers: { "Authorization": "Bearer YOUR_API_KEY" } }); const data = await response.json();
Response
{
"success": true,
"message": "Image img_01jk8mxp3n4q7r2t6w9 has been permanently deleted."
}
GET
/quota
No credit cost
Retrieve your current credit balance and a breakdown of usage by operation type for the current billing period.
Endpoint
GET https://coals.ai/api/v1/graphicoal/quota
Required scope:
graphicoal:read
Response
{
"success": true,
"credits_remaining": 842,
"credits_used_this_period": 158,
"period_start": "2026-03-01T00:00:00Z",
"period_end": "2026-03-31T23:59:59Z",
"usage_breakdown": {
"generate": 64,
"edit": 45,
"analyze": 12,
"svg_generate": 24,
"svg_convert": 13
},
"total_images": 47
}
Response Fields
| Field | Type | Description |
|---|---|---|
| credits_remaining | integer | Credits available in your account balance. |
| credits_used_this_period | integer | Total credits consumed in the current billing period. |
| period_start / period_end | string | ISO 8601 timestamps for the current billing period boundaries. |
| usage_breakdown | object | Credits spent broken down by operation type for the current period. |
| total_images | integer | Total number of images currently stored in your gallery. |