Analyze Image

POST

Submit an image for AI-powered analysis. Provide a question or instruction as the prompt and receive a detailed natural language description or answer. Useful for content moderation, accessibility descriptions, object detection, and data extraction from images. Each analysis consumes 1 credit.

Endpoint

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

Required scope: graphicoal:analyze | Cost: 1 credit per call

Request Parameters

Parameter	Type	Required	Description
prompt	string	required	A question or instruction guiding the analysis (e.g. "Describe what is in this image" or "List all visible text"). Max 2000 characters.
image	string	required	The image to analyze as a base64-encoded data URI (e.g. `data:image/jpeg;base64,...`). PNG, JPEG, and WebP are accepted.

Request Example

curl -X POST https://coals.ai/api/v1/graphicoal/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Describe the main subject, background, and overall mood of this image",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
}'

// Using Guzzle
$response = $client->post('https://coals.ai/api/v1/graphicoal/analyze', [
  'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
  'json' => [
    "prompt" => "Describe the main subject, background, and overall mood of this image",
    "image" => "data =>image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
]
]);
$data = json_decode($response->getBody(), true);

# Using requests
import requests

response = requests.post(
  "https://coals.ai/api/v1/graphicoal/analyze",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={
    "prompt": "Describe the main subject, background, and overall mood of this image",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
}
)
data = response.json()

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

uri = URI("https://coals.ai/api/v1/graphicoal/analyze")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer YOUR_API_KEY"
req["Content-Type"] = "application/json"
req.body = '{
    "prompt": "Describe the main subject, background, and overall mood of this image",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
}'

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/analyze", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "prompt": "Describe the main subject, background, and overall mood of this image",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
})
});
const data = await response.json();

Encode your image to base64 using a command like base64 -i photo.jpg and prefix with the appropriate data URI scheme.

Response

{
  "success": true,
  "analysis": "The image depicts a red fox standing in a snow-covered pine forest during the golden hour. The fox faces the camera with alert amber eyes. The background is softly blurred with warm orange and pink tones filtering through the trees, creating a calm and intimate mood.",
  "credits_charged": 1
}

Response Fields

Field	Type	Description
success	boolean	Always `true` on a successful response.
analysis	string	The AI-generated natural language analysis or answer based on the image and prompt.
credits_charged	integer	Credits deducted from your balance for this analysis.

Example Prompts

Alt text: "Write a concise alt text description for this image suitable for screen readers"

OCR: "Extract and return all visible text from this image"

Moderation: "Does this image contain any explicit, violent, or unsafe content? Answer yes or no and explain"

Product: "List the products visible in this image with their approximate colors and any readable text"