API 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.

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. 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>' \
  --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	Description	Value
`queryToken`	Extracted from the recognition response.	Signed query identifier (string)
`objectIndex`	Object index (0-based) in the `results` array. `null` for whole-image feedback.	Non-negative integer or `null`
`opinion`	Whether user agrees with results.	`Agree`, `Disagree`, or `Unknown` (case-insensitive)
`suggestedSpeciesName`	For "disagree" feedback — the species the user believes is correct.	Any string or `null`

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/comment \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_token>' \
  --data '{
    "queryToken": "<queryToken_from_recognition_response>",
    "opinion": "disagree",
    "objectIndex": 0,
    "suggestedSpeciesName": "Esox lucius"
  }'

Dealing With Large Files

The API imposes a hard limit on maximum file size. 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: