AI Processing

Run AI analysis or processing on an image you have uploaded. Operations run inline — the result is returned in the same response. Tagging and OCR typically complete within a few seconds; background removal within 10–30 seconds.

POST /api/v1/files/:id/ai

Requires a key with write permission and a PRO or ENTERPRISE plan. The file must be an image. Each operation consumes AI credits from your monthly allowance; credits are only charged when the operation succeeds.

Operations

For bg-removal, the source image must be at most 5MB with dimensions between 256px and 4096px.

Request

curl -X POST https://medianest.app/api/v1/files/clx1abc123/ai \
  -H "X-API-Key: mn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"operation": "tagging"}'

Response

{
  "success": true,
  "data": {
    "fileId": "clx1abc123",
    "operation": "tagging",
    "cost": 1,
    "message": "AI tagging completed",
    "result": {
      "tags": ["concert", "crowd", "stage lights"],
      "description": "A large crowd at a concert with raised hands.",
      "confidence": 0.92
    }
  }
}

For ocr, the result contains extractedText instead of tags/description. An empty extractedText means no text was detected in the image.

For bg-removal, the result contains a processedImageUrl — fetch it with your API key to download the transparent PNG:

{
  "result": {
    "processedImageUrl": "https://medianest.app/api/v1/files/clx1abc123/processed?type=bg-removed"
  }
}

Get stored AI results

GET /api/v1/files/:id/ai

Returns the AI data stored on the file (from previous operations, including auto-tagging on upload) plus the processing job history.

curl https://medianest.app/api/v1/files/clx1abc123/ai \
  -H "X-API-Key: mn_your_key_here"

{
  "success": true,
  "data": {
    "fileId": "clx1abc123",
    "ai": {
      "tags": { "tags": ["concert", "crowd"], "confidence": 0.92 },
      "description": "A large crowd at a concert with raised hands.",
      "extractedText": null,
      "processingStatus": "COMPLETED",
      "cost": 1
    }
  }
}

Auto-tagging on upload

Images uploaded on PRO and ENTERPRISE plans are tagged automatically after upload. The tags appear on the file within a few seconds and can be read via the GET endpoint above — no extra request needed.

Errors

Next steps

• Files endpoint — full file parameter reference
• Rate Limits — understand your quota headers