Edit this Page

Introduction DEV API Overview API Reference

Fishial Recognition API Reference

Developer-facing reference for authentication, image recognition, and feedback submission.

Overview

The Fishial Recognition API lets you:

Obtain a short-lived bearer token
Submit an image for fish recognition
Optionally send feedback about the recognition result

The API uses JSON for authentication and feedback requests. Image recognition requests send raw binary image data in the request body.

Base URL

https://api-recognition.fishial.ai

Authentication

Create access token

Obtain a short-lived bearer token required for most API requests.

Endpoint

POST /v2/auth

Content-Type

Content-Type: application/json

Request body

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Fields

client_id — required
client_secret — required for client keys

Success response

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

Notes

Bearer tokens expire after 10 minutes

Example

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

Image Recognition

Recognize fish in an image

Scan an image and return detected fish objects with candidate species matches.

Endpoint

POST /v2/recognize

Authorization

Authorization: Bearer YOUR_ACCESS_TOKEN

Request body

Raw binary image data
Do not use multipart form data

Content-Type

You may send the image MIME type directly:

Content-Type: image/jpeg

or use a generic binary type:

Content-Type: application/octet-stream

Both are accepted according to the current docs.

Supported formats

Raster

AVIF
GIF
HEIC
HEIF
JPEG
JPEG 2000
JPEG XL
PNG
TIFF
WebP

Vector

Not supported

Limits

Maximum request body size: 20 MB

Success response

{
  "ok": true,
  "queryToken": "QUERY_TOKEN",
  "objects": [
    {
      "shape": [12.4, 40.1, 20.2, 38.6, 28.9, 45.0],
      "bbox": [12, 38, 90, 120],
      "species": [
        {
          "id": "SPECIES_UUID",
          "certainty": 0.97
        }
      ]
    }
  ],
  "definitions": {
    "SPECIES_UUID": {
      "commonName": "Mahi-mahi",
      "scientificName": "Coryphaena hippurus",
      "imageUrl": "https://..."
    }
  }
}

Response fields

ok — boolean success indicator
queryToken — token required when sending feedback for this recognition result
objects — array of detected fish objects (best species match first)
objects[].shape — fish outline polygon as coordinate pairs
Format:
```
[x1, y1, x2, y2, ...]
```
objects[].bbox — bounding box in the form:
```
[x1, y1, x2, y2]
```
objects[].species — candidate species matches for the object
objects[].species[].id — species UUID
objects[].species[].certainty — confidence value from 0.0 to 1.0
- Values > .80 is high confidence
- Values < .30 is low confidence
definitions — lookup map from species UUID to display metadata
definitions[speciesId].commonName — common English name
definitions[speciesId].scientificName — Latin binomial
definitions[speciesId].imageUrl — reference image URL

Example

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/recognize \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: image/jpeg" \
  --data-binary @fish.jpg

Recognition Options

Recognition options are passed as custom HTTP headers on the /v2/recognize request.

Header value restrictions

Header values should use only:

ASCII alphanumeric characters
Spaces
Basic punctuation

Avoid:

Diacritics
CJK characters
Emoji
Line breaks

Detection quality headers

`Fishial-Fish-Detection-Threshold`

Controls fish detection sensitivity.

Accepted range: 0.3 to 1.0
Lower values may detect more fish shapes, but can increase false positives

Example:

Fishial-Fish-Detection-Threshold: 0.5

`Fishial-Fish-Shape-Max-Points`

Controls the maximum number of points in the detected fish polygon.

Higher values produce more detailed outlines
Lower values produce simpler shapes

Example:

Fishial-Fish-Shape-Max-Points: 64

Portal Collection Headers

These headers apply only when the image is being uploaded to a Fishial Portal collection. They are not described as general-purpose recognition parameters.

Privacy

`Fishial-Face-Obfuscation`

Blurs detected human faces. The source docs note that this may partially blur fish if a face is too close.

Example:

Fishial-Face-Obfuscation: true

Image licensing metadata

`Fishial-Image-License-Code`

Allowed values include:

None
Unknown
Custom
SPDX-style license values such as:
- CC0-1.0
- CC-BY-4.0
- CC-BY-NC-4.0
- CC-BY-NC-ND-4.0
- CC-BY-NC-SA-4.0
- CC-BY-ND-4.0
- CC-BY-SA-4.0

`Fishial-Image-License-Url`

License URL, primarily relevant when using Custom.

`Fishial-Image-License-Author`

Name of the image author.

`Fishial-Image-License-Source`

Text or URL describing where the image came from.

`Fishial-Image-License-Notice`

Additional copyright information.

Additional metadata

`Fishial-Image-Tags`

Comma-separated list of tags.

Examples:

Fishial-Image-Tags: wow,a,tag

Creates three tags.

Fishial-Image-Tags: wow a tag

Creates one tag.

`Fishial-Location-Lat-Lon`

Observation coordinates in decimal degrees.

Example:

Fishial-Location-Lat-Lon: -55.260, -67.886

User Feedback

Submit feedback for a recognition result

Send user feedback about a recognition response.

Endpoint

POST /v2/feedback

Authorization

Authorization: Bearer YOUR_ACCESS_TOKEN

Content-Type

Content-Type: application/json

Request body

{
  "queryToken": "QUERY_TOKEN",
  "objectIndex": 0,
  "opinion": "Disagree",
  "suggestedSpeciesName": "Yellowfin tuna",
  "suggestedSpeciesID": "SPECIES_UUID"
}

Fields

queryToken — required; returned by /v2/recognize
objectIndex — required; zero-based object index in the recognition response
- Set to null to refer to the recognition result as a whole, for example when no fish was found
opinion — required; one of:
- Agree
- Disagree
- Unsure
suggestedSpeciesName — optional suggested correction
suggestedSpeciesID — optional suggested correction using a species UUID

Success response

{
  "ok": true
}

Notes

Multiple feedback submissions for the same recognition result are explicitly allowed

Example

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/feedback \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "queryToken": "QUERY_TOKEN",
    "objectIndex": 0,
    "opinion": "Agree"
  }'

Error Responses

Unless otherwise noted, errors follow this schema:

{
  "ok": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}

Fields

ok — false on error
error — machine-readable error code suitable for application handling
message — human-readable English description; do not rely on exact wording for program logic

Some server-side 5xx responses may not follow this schema or may not be valid JSON.

General error codes

auth_token_expired — bearer token expired; request a new token
auth_token_invalid — bearer token invalid
credits_insufficient — not enough API credits

Recognition error codes

unsupported_file_format — image format not supported

Feedback error codes

feedback_invalid — invalid feedback request
query_token_invalid — queryToken expired or invalid

Minimal Integration Flow

1. Get a token

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

2. Recognize an image

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/recognize \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: image/jpeg" \
  --data-binary @fish.jpg

3. Send feedback

curl --request POST \
  --url https://api-recognition.fishial.ai/v2/feedback \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "queryToken": "QUERY_TOKEN",
    "objectIndex": 0,
    "opinion": "Unsure"
  }'