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

Send an image you have on hand (upload then infer)

Every client uses the same raw_key path. If your client has the image file in hand (a mobile app, a script, or Postman), first request a presigned URL from POST /api/v1/image_diagnosis/uploads/presign, PUT the bytes to it, then call infer with the returned raw_key. Posting the file directly to the infer endpoint as multipart is not supported (it returns 400). The examples below show that upload-then-infer sequence.

import requests

base = "https://api.fildraai.com/api/v1"
headers = {"X-Api-Key": "YOUR_USER_API_KEY"}
img_path = "/absolute/path/to/maize_leaf.jpg"

# 1) Ask for a presigned PUT URL (free).
presign = requests.post(
    f"{base}/image_diagnosis/uploads/presign",
    headers=headers,
    json={"content_type": "image/jpeg", "size_bytes": 204800},
    timeout=30,
).json()
put_url, raw_key = presign["put_url"], presign["raw_key"]

# 2) PUT the raw bytes straight to storage (no API key on this request).
with open(img_path, "rb") as fh:
    requests.put(put_url, data=fh, headers={"Content-Type": "image/jpeg"}, timeout=60).raise_for_status()

# 3) Infer with the returned raw_key (JSON body, not multipart).
response = requests.post(
    f"{base}/image_diagnosis/infer/basic",
    headers=headers,
    json={"plant": "maize", "raw_key": raw_key, "top_k": 3, "locale": "en-us"},
    timeout=60,
)
response.raise_for_status()
print(response.json())

// Works in browsers and Node 18+ (built-in fetch).
const base = 'https://api.fildraai.com/api/v1';
const headers = { 'X-Api-Key': 'YOUR_USER_API_KEY' };

async function diagnoseImage(file) {
  // 1) Presign (free).
  const presign = await (await fetch(`${base}/image_diagnosis/uploads/presign`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ content_type: file.type || 'image/jpeg', size_bytes: file.size }),
  })).json();

  // 2) PUT the bytes to storage (no API key on this request).
  await fetch(presign.put_url, { method: 'PUT', headers: { 'Content-Type': file.type || 'image/jpeg' }, body: file });

  // 3) Infer with the raw_key (JSON body, not multipart).
  const response = await fetch(`${base}/image_diagnosis/infer/basic`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/json' },
    body: JSON.stringify({ plant: 'maize', raw_key: presign.raw_key, top_k: 3, locale: 'en-us' }),
  });
  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 steps below mirror what the Python and JavaScript snippets do above: presign, PUT the bytes, then infer with the raw_key. Posting the image straight to the infer endpoint as form-data is not supported and returns 400.

1. Request a presigned URL. Method POST, URL https://api.fildraai.com/api/v1/image_diagnosis/uploads/presign. Under Headers add X-Api-Key (your user-audience key) and Content-Type: application/json. Under Body select raw + JSON and send {"content_type":"image/jpeg","size_bytes":204800}. The response contains put_url and raw_key.
2. Upload the image bytes. New request: method PUT, URL = the put_url from step 1 (no API key on this request). Add header Content-Type: image/jpeg. Under Body select binary and pick your JPEG. Send and expect 200.
3. Run inference. New request: method POST, URL https://api.fildraai.com/api/v1/image_diagnosis/infer/basic. Headers X-Api-Key + Content-Type: application/json. Under Body select raw + JSON and send {"plant":"maize","raw_key":"PASTE_raw_key_FROM_STEP_1","top_k":3,"locale":"en-us"}.
4. Read the result. 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 the image posted directly to infer as form-data, which is not supported).

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/<id>.jpg",
  "kb_available_locales": ["en-us", "es-ar", "fr-af", "pt-ao", "sw-ke", "zh-cn", "zh-tw"],
  "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

Common mistakes and good to know

• Do not post the image as multipart to the infer endpoint. It returns 400. Presign, PUT the bytes, then infer with the returned raw_key.
• The raw_key comes from the presign response, not from your local filename.
• The image cap is 15 MiB. The presign request rejects a larger size_bytes with 400, so validate the file size before uploading.
• locale defaults to en-us when omitted, and top_k is clamped to a maximum of 10.
• gradcam_url is a signed link that expires in about 15 minutes. Fetch or cache the overlay before then if you need it offline.
• job_id is returned for your logs and tracking. It is a correlation id; you do not need to send one.