🟢API for Images

This page contains description of images management via API.

Image is a data source object that is used by Algorithmsto extract information and convert it into knowledge (for example, the estimation of skin concerns)

What can you do?

You can find more details on these actions in the Images section of Swagger.

Sides and lights IDs

side_id: 1 - front image

side_id: 2 - right image

side_id: 3 - left image

light_id: 1 - regular light

Upload

Generate signed URL for upload

Generate signed URL to upload image to subject

post

Underlying batch to store image is created automatically. Don't forget to call /compute/ method when the upload is done

Authorizations
Path parameters
company_idstring · uuidRequired
subject_idstring · uuidRequired
Body
batch_idstring · uuidOptional

image batch id (uuid)

side_idintegerOptional

image side id related to dataset's image_type, you can choose a side from /dicts/image_types/ API endpoint, if you omit this parameter, the default side will be used

light_idinteger | nullOptional

image light id related to dataset's image_type, you can choose a light from /dicts/image_types/ API endpoint, if you omit this parameter, the default side will be used

metaone ofOptional

image meta

Default: {}
anyOptional
or
nullOptional
creation_timestring | nullOptional

batch creation time

namestring · min: 1Optional
app_argsone ofOptional
anyOptional
or
nullOptional
Responses
201Success
application/json
post
POST /api/v1/companies/{company_id}/subjects/{subject_id}/signed_upload_url/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "side_id": 1,
  "light_id": null,
  "meta": null,
  "creation_time": null,
  "name": "text",
  "app_args": null
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "side": {
    "id": 1,
    "name": "text",
    "tech_name": "text"
  },
  "light": {
    "id": 1,
    "name": "text",
    "tech_name": "text"
  },
  "image_type": {
    "id": 1,
    "name": "text",
    "tech_name": "text"
  },
  "side_name": "text",
  "side_tech_name": "text",
  "light_name": "text",
  "light_tech_name": "text",
  "image_type_name": "text",
  "image_type_tech_name": "text",
  "creation_time": "2025-10-08T20:00:55.784Z",
  "quality_score": null,
  "quality_feedback": null,
  "quality_result": null,
  "quality_issues": [
    "text"
  ],
  "problems": [
    "text"
  ],
  "stage_step_number": null,
  "stage_number": null,
  "urls": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "signed_url": null,
  "original_image_id": null,
  "image_batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "meta": null,
  "application_run_id": "123e4567-e89b-12d3-a456-426614174000",
  "upload_url": {
    "url": "https://example.com",
    "method": "text",
    "headers": null,
    "content_type": null
  }
}

When you've created a subject connected to your user, you can now request a signed URL to upload the image.

In the simplest case (uploading 1 frontal selfie to subject), you don't even need to send any extra payload in the body of this request.

After you've received response from this API method, you should take the key from response upload_url. It will contain following keys:

  • url — the URL where to upload your image

  • method — HTTP method that you should use for upload (PUT by default)

  • headersrequired headers to make an upload request

Also you need to save the response key image_batch_id to a variable in your code, it will be needed later. Batch is simply a grouping of images in one group. In the simplest case when you upload only selfies, it's just a group of 1 image.

Then you perform an upload request:

curl -X PUT {upload_url.url} \
  -H "Content-Type: application/octet-stream" \
  -H "X-Goog-Content-Length-Range: 1,31457280" \
  --upload-file {file_name}

Image requirements:

  • Minimum image resolution is 256x256 pixels.

  • Maximum resolution is not restricted, but remember - the heavier is the picture, the longer it's being processed.

  • Maximum image size is 30MB. The optimal image size is an average modern smartphone selfie (3-5MB).

  • Images should be in one of these file formats:

    • JPEG

    • PNG

    • WEBP


Send to computation

After the upload is done, you should send signal to SaaS API backend, that upload is complete and we should start processing your image by algorithms.

Use previously saved image_batch_id as a batch_id here. The request body can be empty.

Send batch images to algorithms for processing

post

Send batch images to algorithms for processing

Authorizations
Path parameters
company_idstring · uuidRequired
batch_idstring · uuidRequired
Body
app_argsanyOptional
Responses
200Success
application/json
post
POST /api/v1/companies/{company_id}/batches/{batch_id}/compute/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "app_args": null
}
{
  "ok": true
}


List subject images

List subject images

get

List subject images

Authorizations
Path parameters
company_idstring · uuidRequired
subject_idstring · uuidRequired
Query parameters
orderingstringOptional

Which field to use when ordering the results.

qstringOptional

A search term.

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

expiration_secondsintegerOptional

expiration seconds for signed url

Default: 60
Responses
200Success
application/json
get
GET /api/v1/companies/{company_id}/subjects/{subject_id}/images/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200Success
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "side": "text",
      "quality_score": null,
      "problems": null,
      "created_at": "2025-10-08T20:00:55.784Z",
      "signed_url": null,
      "image_batch_id": "123e4567-e89b-12d3-a456-426614174000",
      "meta": null,
      "aux_images": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "aux_image_type": "text",
          "creation_time": "2025-10-08T20:00:55.784Z",
          "algo_app": "text",
          "signed_url": null,
          "meta": null
        }
      ]
    }
  ]
}

Note that you can access aux images (aux images API link) directly in this response.


Get image info

Get image

get

Get image

Authorizations
Path parameters
company_idstring · uuidRequired
image_idstring · uuidRequired
Query parameters
generate_signed_urlbooleanOptional

generate signed url

Default: false
expiration_secondsintegerOptional

expiration seconds for signed url

Default: 60
Responses
200Success
application/json
get
GET /api/v1/companies/{company_id}/images/{image_id}/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200Success
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "side": "text",
  "quality_score": null,
  "problems": null,
  "created_at": "2025-10-08T20:00:55.784Z",
  "signed_url": null,
  "image_batch_id": "123e4567-e89b-12d3-a456-426614174000",
  "meta": null,
  "aux_images": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "aux_image_type": "text",
      "creation_time": "2025-10-08T20:00:55.784Z",
      "algo_app": "text",
      "signed_url": null,
      "meta": null
    }
  ]
}

Note that you can access aux images (aux images API link) directly in this response.


Delete image

Delete image

delete

Delete image

Authorizations
Path parameters
company_idstring · uuidRequired
image_idstring · uuidRequired
Responses
204

No response body

No content

delete
DELETE /api/v1/companies/{company_id}/images/{image_id}/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
204

No response body

No content

Last updated

Was this helpful?