API GUIDE

Fishial Recognition Guide

Initial notes

• Authorization Tokens are JWT with 10 minutes expiration time
• API features are available at two host names, specifically i.e. api.fishial.ai and api-users.fishial.ai (production), or api.fishial.ai and api-users.fishial.ai.
• Stage servers (*.fishial.ai) SSL certificates are expired at the moment, hence "-k" is needed in cURL, or similar means in other clients.
• Stage servers typically run more recent logic. Something that doesn't work in production yet may work in stage.

Obtaining Client Keys

Client Key ID and Client Secret Key can be created in portal, on "For Developers" page.

Preparing image for recognition

Following information must be gathered:

• image file name, e.g. file.jpg
• image MIME type, e.g. image/jpeg
• image byte size, as in wc -c path/to/file.jpg
• image MD5 checksum base64-encoded, as in openssl dgst -md5 -binary < path/to/file.jpg | openssl enc -base64

Algorithm for image recognition

1. Obtain an access token
2. Obtain a URL for image upload
3. Upload image file to a URL returned in step 2
4. Actually run fish recognition

API calls for image recognition

1. Obtaining an access token

prerequisites:

• Client Key ID and Client Secret Key (to be passed in request body)

obtained data:

• access token

request:

curl --request POST \
  --url https://api-users.fishial.ai/v1/auth/token \
  --header 'Content-Type: application/json' \
  --data '{"client_id": "<redacted>", "client_secret": "<redacted>"}'

response:

{"token_type":"Bearer","access_token":"<redacted>"}

2. Obtaining a URL for image upload

prerequisites:

• access token (to be passed in Authorization header)
• file name, MIME type, byte size, and MD5 checksum (to be passed in request body)

obtained data:

• upload URL (direct_upload -> url in response body)
• upload headers (direct_upload -> headers in response body)
• image signed ID (signed_id in response body)

request:

curl --request POST \
  --url https://api.fishial.ai/v1/recognition/upload \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <redacted>' \
  --header 'Content-Type: application/json' \
  --data '{
    "blob": {
      "filename": "Esox lucius.jpg",
      "content_type": "image/jpeg",
      "byte_size": 2204455,
      "checksum": "EA5w4bPQDfzBgEbes8ZmuQ=="
    }
  }'

response:

{
  "id": 134429,
  "key": "p5tcq31tlb32yz8lmo8a1cr9v1g1",
  "filename": "Esox lucius.jpg",
  "content-type": "image/jpeg",
  "metadata": {},
  "byte-size": 2204455,
  "checksum": "EA5w4bPQDfzBgEbes8ZmuQ==",
  "created-at": "2022-03-31T01:37:53.830Z",
  "service-name": "google_stage",
  "signed-id": "<redacted>",
  "attachable-sgid": "<redacted>",
  "direct-upload": {
    "url": "https://storage.googleapis.com/<redacted>",
    "headers": {
      "Content-MD5": "EA5w4bPQDfzBgEbes8ZmuQ==",
      "Content-Disposition": "inline; filename=\"Esox lucius.jpg\"; filename*=UTF-8''Esox%20lucius.jpg"
    }
  }
}

3. Uploading picture to the cloud

prerequisites:

• upload URL and headers
• image byte size (to be passed in Content-Length header)

request:

curl --request PUT \
  --url '<redacted>' \
  --header 'Content-Disposition: inline; filename="Esox lucius.jpg"; filename*=UTF-8'\'''\''Esox%20lucius.jpg' \
  --header 'Content-Length: 2204455' \
  --header 'Content-Md5: EA5w4bPQDfzBgEbes8ZmuQ==' \
  --data <image binary data>

response: (no body)

4. Running picture recognition

prerequisites:

• access token (to be passed in Authorization header)
• image signed ID (to be passed as a query argument q)

request:

curl --request GET \
  --url 'https://api.fishial.ai/v1/recognition/image?q=<redacted>' \
  --header 'Authorization: Bearer <redacted>'

response: (to be documented)