Image diagnosis on the live FildraAI API with honest endpoint status and audience boundaries

Send an image directly (multipart upload)

The examples above use raw_key, the server-side path. If your client has the image file in hand (a mobile app, a script, or Postman), use the multipart upload form below instead. The API accepts the file under the image form field plus a plant form field or ?plant= query parameter.

import requests

url = "https://api.fildraai.com/api/v1/image_diagnosis/infer/basic"
headers = {"X-Api-Key": "YOUR_USER_API_KEY"}

# `files` triggers multipart/form-data automatically.
# `data` carries non-file form fields alongside the upload.
with open("/absolute/path/to/maize_leaf.jpg", "rb") as fh:
    response = requests.post(
        url,
        headers=headers,
        data={"plant": "maize", "locale": "en-us", "top_k": 3},
        files={"image": ("maize_leaf.jpg", fh, "image/jpeg")},
        timeout=60,
    )

response.raise_for_status()
print(response.json())

// Works in browsers and Node 18+ (built-in fetch + FormData).
// `fileInput` is <input type="file">, use the first selected file.
async function diagnoseImage(file) {
  const form = new FormData();
  form.append('image', file, file.name);
  form.append('plant', 'maize');
  form.append('locale', 'en-us');
  form.append('top_k', '3');

  const response = await fetch(
    'https://api.fildraai.com/api/v1/image_diagnosis/infer/basic',
    {
      method: 'POST',
      headers: { 'X-Api-Key': 'YOUR_USER_API_KEY' },
      // IMPORTANT: do NOT set Content-Type, the browser sets the
      // correct multipart boundary automatically when you pass FormData.
      body: form,
    }
  );

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

Test in Postman

Postman is the fastest way to verify your API key and image work before wiring up code. The five steps below mirror what the Python and JavaScript snippets do above.

1. Create a new request. Method POST, URL https://api.fildraai.com/api/v1/image_diagnosis/infer/basic.
2. Add the API key header. Under the Headers tab, add X-Api-Key with your user-audience key as the value.
3. Switch the body to multipart. Under the Body tab, select form-data (not raw / x-www-form-urlencoded).
4. Add the image and form fields. Create a key called image, hover the right edge of the key cell, change its type from Text to File, then pick your JPEG. Add four more text rows: plant=maize, locale=en-us, top_k=3.
5. Send it. A successful response returns 200 with a predictions array. Common failures: 401 (key missing/wrong), 403 (key audience or scope mismatch), 400 (plant not in cassava/maize/rice/tomato, or file isn't a real JPEG/PNG).

Screenshots below, drop the captured PNGs into /static/img/docs/postman/ with the filenames shown.

Response Examples

Successful response

The raw-key diagnosis response currently returns the diagnosis fields directly. It does not include a top-level success flag or gateway block.

{
  "plant": "maize",
  "locale": "en-us",
  "kb_locale": "en-us",
  "job_id": "2ae7df30-3e3b-4d7b-b89d-6626a3d08b02",
  "top_k": 3,
  "raw_key": "uploads/fieldvision/codex_live_api_validation_6f477789fa.jpg",
  "result_key": "diagnostics/gradcams/2ae7df30-3e3b-4d7b-b89d-6626a3d08b02/result.json",
  "result_url": "https://signed-storage-url.example/result.json",
  "predictions": [
    {
      "class_index": 4,
      "label": "grey_leaf_spot",
      "confidence": 0.9412,
      "gradcam_key": "diagnostics/gradcams/.../pred_1.png",
      "gradcam_url": "https://signed-storage-url.example/pred_1.png"
    },
    {
      "class_index": 2,
      "label": "common_rust",
      "confidence": 0.0418,
      "gradcam_key": "diagnostics/gradcams/.../pred_2.png",
      "gradcam_url": "https://signed-storage-url.example/pred_2.png"
    }
  ],
  "inference_plants": ["cassava", "maize", "rice", "tomato"],
  "supported_plants": ["cassava", "maize", "rice", "tomato"]
}

Error response

Validation, authentication, quota, and server failures should all be handled explicitly in client code.

{
  "success": false,
  "error": "bad_request",
  "message": "Unsupported plant: 'wheat'. Supported plants: cassava, maize, rice, tomato",
  "status_code": 400
}

Common error classes

• 400 Bad Request: missing query parameter, unsupported plant, invalid image type, empty file, or file too large
• 401 Unauthorized: missing API key or invalid API key
• 403 Forbidden: wrong audience, missing scope, or API not allowed for the key
• Quota exceeded: usage rejected after the configured guest, authenticated, or API-key quota is exhausted
• 500 Internal Server Error: storage or diagnosis engine failure