API V2 Tutorial

Introduction

This step-by-step tutorial shows how to perform fish recognition on a picture of a northern pike (Esox lucius).

Sample image: https://raw.githubusercontent.com/fishial/devapi/main/fishpic.jpg

curl "https://raw.githubusercontent.com/fishial/devapi/main/fishpic.jpg" -o fishpic.jpg

Prerequisites

You need an active Developers' API subscription with generated API credentials (API Key ID and API Secret Key).

Field Example Value (expired — do not use)
API Key ID c0fae174f24c0950352c2bbd
API Secret Key 5edac99f92bf7acb66425c47fb153c5f

Warning: Never reveal your API Secret Key to anyone or pass it to untrusted devices.

Image requirements

The image you submit for recognition must meet these constraints:

Step 1 — Obtain an Access Token

Send your API credentials to the auth endpoint to get a short-lived bearer token:

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/auth \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "YOUR_API_KEY_ID",
    "client_secret": "YOUR_API_SECRET_KEY"
  }'

Example response:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJqdXN0Ijoia2lkZGluZyJ9.Wp2EkrHpdPc9qiKscvYL_K2jN6uUPn_7F_Lt0XYuh1Y"
}

The bearer token is valid for 10 minutes (600 seconds). Include it in the Authorization HTTP header for subsequent calls:

Authorization: Bearer <access_token>

The token may be passed to client devices without compromising the API Secret Key.

Step 2 — Image Recognition

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/recognize \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: image/jpeg' \
  --data-binary @fishpic.jpg

The response contains detection results: fish outlines, matched species, and certainty rates. If your API key has an upload folder configured, the image will also be added to that folder in the Fishial Portal.

Step 3 — Customizing Recognition (Optional)

Recognition options are set via HTTP headers. For example, to set a fish detection threshold of 0.9, provide GPS coordinates, and set a "None" image license:

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/recognize \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Fishial-Fish-Detection-Threshold: 0.9' \
  --header 'Fishial-Location-Lat-Lon: -55.260, -67.886' \
  --header 'Fishial-Image-License-Code: None' \
  --data-binary @fishpic.jpg

See Supported Recognition Options for all available headers.

Step 4 — Sending Feedback (Optional)

Submit user feedback on recognition results:

Attribute Required Description Value
queryToken ✓ From the recognition response. Signed query identifier (string)
objectIndex ✓ Object index (0-based) in the objects array. null for whole-image feedback. Non-negative integer or null
opinion ✓ User's verdict on the result. Values are case-sensitive. Agree, Disagree, or Unsure
suggestedSpeciesName User-suggested species (common or scientific name). Any string
suggestedSpeciesID User-suggested species as a UUID from the Fishial species list. UUID string 
curl --request POST \
  --url https://api-recognition.fishial.ai/v2/feedback \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "queryToken": "<queryToken_from_recognition_response>",
    "objectIndex": 0,
    "opinion": "Disagree",
    "suggestedSpeciesName": "Esox masquinongy"
  }'

Dealing With Large Files

The API enforces a maximum request body size of 20 MB. Requests over the limit return HTTP 413. Strategies for reducing file size:

Downscaling — Scale the image down. Fewer pixels = smaller file. Note: results will be based on the scaled image, not the original.

Changing file format — PNG is a poor choice for photos. TIFF files are often very large. JPEG works well in most cases; modern alternatives like WebP, JPEG-XL, or AVIF can reduce size further.

Lossy compression — Reducing JPEG quality settings can help significantly.

Further reading: