AI services

Integrate image classification

Send a photo and get back the most likely labels for what's in it, each with a confidence score.

What this does and doesn't do

Not a fit for identifying one specific item

resnet-50 sorts a photo into one of ImageNet's 1,000 general categories, things like "golden retriever" or "coffee mug", rather than recognizing a particular instance of anything. It cannot tell your product apart from a similar one, read text, recognize a specific person, or count how many objects are in a photo. Point it at a photo expecting a precise, specific answer and you will get a confident-sounding but wrong label, and that is a mismatch with what this model does, not a defect in it.

For faces, use face comparison. For locating protective equipment worn by people, use PPE detection. Neither of those recognizes one specific everyday object either; nothing on this platform currently does, since that needs a model trained on your own categories rather than ImageNet's general ones.

Request

Send multipart/form-data with one image:

Field	Meaning
`image`	image is required. JPEG or PNG, up to 10 MB.

Examples

curl -X POST https://core.roammoon.com/v1/ai/image-classification/classify \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -F "image=@photo.jpg"

Response

Returns every label the model considered, most confident first:

JSON

{
  "predictions": [
    { "label": "Egyptian cat", "confidence": 0.91 },
    { "label": "tabby, tabby cat", "confidence": 0.06 },
    { "label": "tiger cat", "confidence": 0.02 }
  ]
}

Fields that matter

Field	Meaning
`predictions`	One entry per label the model returned, sorted by confidence.
`predictions[].label`	The predicted class name, drawn from the 1,000 ImageNet categories resnet-50 was trained on.
`predictions[].confidence`	Model confidence for this label, 0-1.

Billing

1 credit is charged only when the classification succeeds and a result is returned. Every failure is refunded, whether the image was rejected or the model itself could not complete the request.

The charge policy is charge-on-success: credit is reserved when the request is accepted and only committed once processing succeeds. A failure refunds the reservation.

Getting good results

A single clear subject filling a meaningful part of the frame works best, since resnet-50 classifies the whole image rather than locating anything within it.
Labels come from ImageNet's 1,000 categories, mostly everyday objects, animals and scenes, so an unusual subject may return a plausible but imprecise label.
Treat this as a fast first pass, not a guarantee. A low-confidence prediction is worth a second look before anything acts on it automatically.

Errors

Every error uses the same shape. Branch on code, not on message, because messages can change.

JSON

{
  "error": {
    "code": "UNSUPPORTED_IMAGE_TYPE",
    "message": "Image classification accepts JPEG or PNG images only."
  }
}

HTTP	Code	What to do
401	`API_KEY_REQUIRED`	The X-API-Key header is missing.
401	`API_KEY_INVALID`	The key is wrong, disabled or expired. Check it or create a new one.
403	`API_KEY_FORBIDDEN`	The key is not permitted to use this service.
400	`INVALID_IMAGE_CLASSIFICATION_REQUEST`	The "image" field is missing or empty. No credit is charged.
402	`CREDIT_LIMIT_EXCEEDED`	The period's credits are exhausted. Upgrade or wait for the next period.
413	`IMAGE_TOO_LARGE`	The image exceeds 10 MB. Compress or resize it.
415	`UNSUPPORTED_IMAGE_TYPE`	Only JPEG and PNG are supported.
429	`RATE_LIMIT_EXCEEDED`	Per-minute request limit exceeded. Slow down.
502	`IMAGE_CLASSIFICATION_UPSTREAM_ERROR`	The image classification model could not complete the request. Retryable.

Retrying safely

502 is retryable, so use exponential backoff. Other errors return the same result on retry. Only a successful classification is charged, so retrying after a failure costs nothing extra. The exception is a network timeout: if the first attempt actually succeeded, the retry is charged as a second call.

Next: API reference →