Fishial Recognition API V2 Reference

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

Overview

The Fishial Recognition API lets you:

  1. Obtain a short-lived bearer token
  2. Submit an image for fish recognition
  3. 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

Field Required Description
client_id ✓ API Key ID provided by Fishial.
client_secret ✓ API Secret Key provided by Fishial.

Success response

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

Notes

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

Content-Type

The server detects the image format from the file's magic bytes, not from the Content-Type header value. Any of the following are accepted for a valid image body:

A Content-Type header that does not start with image/ or application/octet-stream (for example text/plain or text/html) will be rejected. A missing Content-Type header returns HTTP 400.

Examples:

Content-Type: image/jpeg
Content-Type: application/octet-stream

Supported formats

Raster

Vector

Not supported

Limits

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

Field Type Description
ok boolean Success indicator.
queryToken string Token required when sending feedback for this recognition result.
objects array Detected fish objects, best species match first.
objects[].shape array of numbers Fish outline polygon as flat coordinate pairs: [x1, y1, x2, y2, ...].
objects[].bbox array of 4 numbers Bounding box as [x1, y1, x2, y2].
objects[].species array Candidate species matches for the object.
objects[].species[].id string (UUID) Species UUID; look up in definitions.
objects[].species[].certainty number Confidence value, 0.0–1.0. Values > 0.80 are high confidence; values < 0.30 are low confidence.
definitions object (map) Lookup map from species UUID to display metadata.
definitions[speciesId].commonName string Common English name.
definitions[speciesId].scientificName string Latin binomial.
definitions[speciesId].imageUrl string (URL) 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

✓ Use ✗ Avoid
ASCII alphanumeric characters Diacritics (é, ñ, ö, …)
Spaces CJK characters (Chinese, Japanese, Korean)
Basic punctuation Emoji and other non–Latin-1 characters
Line breaks

Header values containing emoji or non–Latin-1 characters can cause HTTP 500 errors. Sanitize tag and metadata values to ASCII or Latin-1 before sending.

Detection quality headers

Fishial-Fish-Detection-Threshold

Controls fish detection sensitivity.

Example:

Fishial-Fish-Detection-Threshold: 0.5

Fishial-Fish-Shape-Max-Points

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

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:

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

Field Required Type Description
queryToken ✓ string Returned by /v2/recognize.
objectIndex ✓ integer or null Zero-based object index in the objects array. Set to null to refer to the recognition result as a whole (e.g. when no fish was found).
opinion ✓ string One of Agree, Disagree, or Unsure. Case-sensitive.
suggestedSpeciesName string Suggested correction by common or scientific name.
suggestedSpeciesID string (UUID) Suggested correction using a species UUID.

Success response

{
  "ok": true
}

Notes

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

Field Type Description
ok boolean false on error.
error string Machine-readable error code suitable for application handling.
message string Human-readable English description. Do not rely on exact wording for program logic.

Authentication error codes

Error code HTTP Description
invalid_client 401 client_id or client_secret is missing, incorrect, or of the wrong type.
auth_token_expired 401 Bearer token expired; request a new token.
auth_token_invalid 401 Bearer token missing, malformed, or invalid.

Recognition error codes

Error code HTTP Description
unsupported_file_format 415 Request body is not a recognized image format. Also returned for empty bodies, base64-encoded text, and multipart form-data.
malformed_file 415 Image bytes are corrupt, truncated, or cannot be decoded as a supported format.
image_dimensions 422 Image is smaller than the 32 × 32 pixel minimum.
bad_recognition_option 400 A Fishial-* recognition header has an invalid value.
credits_insufficient — Account has insufficient API credits.

Feedback error codes

Error code HTTP Description
query_token_invalid 401 queryToken is expired, invalid, or fails any other feedback validation check. This is the catch-all for most feedback failures (wrong field types, out-of-range values, invalid opinion values, etc.).

Fully malformed requests — missing required fields, broken JSON, missing Content-Type — return HTTP 400 rather than a structured feedback error code.

Edge and framework errors

Some responses from the edge proxy or framework — notably HTTP 400, 413, and 5xx — may return a non-JSON body (HTML or plain text) and may not follow the standard error schema above. Clients must handle non-JSON error responses gracefully rather than assuming every error parses as JSON.

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"
  }'