Quick Start

This section shows the basic flow for using the API: from submitting a file to obtaining the processing results.

The general flow consists of four steps:

1. Upload or submit the file for processing
2. Obtain the task identifier
3. Check the processing status
4. Retrieve the results

Submitting a file for processing

First, you need to upload the file you want to analyze to the platform.

To do this, you must make an authenticated request to the API, including the API Key in the header.

Example request:

curl -X POST 'https://fair-dev.gradiant.org/api/v1/files' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=...'

This request will return a unique identifier for the file. This identifier is used to initiate any further operations on the file.

{
  "file_ids": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ]
}

To analyze the document, we indicate that ID in the corresponding endpoint:

Example with curl:

curl -X 'POST' \
  'https://fair-dev.gradiant.org/api/v1/runs' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY} \
  -H 'Content-Type: application/json' \
  -d '{
  "run_type": "detection",
  "file_ids": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ],
  "strength": 0,
  "algorithm": "string",
  "lang": "string",
  "context": "string",
  "threshold": 0,
  "top_n": 0,
  "exact_duplicated": true
}'

If the request is successful, the API will respond with JSON similar to:

{
  "success_queued_files": [
    "ac38014e-7b31-470d-b013-dc5318055adc"
  ],
  "error_queued_files": [],
  "run_ids": [
    "40fa5bb8-37b7-45d1-9647-14233e490c5f"
  ],
  "details": [
    "file SDXL_1261.webp ok"
  ]
}

The run_ids field contains The unique identifiers for each task will be required to check its status and results.

Checking Task Status

Processing may not be immediate, especially for long videos or audio files. To check the status, use the following endpoint, including the corresponding run_id:

curl -X 'GET' \
  'https://fair-dev.gradiant.org/api/v1/runs/40fa5bb8-37b7-45d1-9647-14233e490c5f/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}"

Example response while processing:

{
  "status": "processing"
}

When the status changes to:

{
  "status": "ok",
  "result_ids": [
    "2df5032e-9506-47ea-a0fe-dbd642faa5ee"
  ]
}

This means the results are now available.

Get the results

Once the task is complete, the results can be retrieved by requesting the available information about the file with the corresponding file_id:

curl -X 'GET' \
  'https://fair-dev.gradiant.org/api/v1/files/ac38014e-7b31-470d-b013-dc5318055adc' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {API_KEY}"

Example response:

{
  "id": "ac38014e-7b31-470d-b013-dc5318055adc",
  "type": "image/webp",
  "format": "image",
  "filename": "SDXL_1261.webp",
  "state": "ready",
  "detection_state": {
    "state": "alert",
    "detail": null,
    "remaining_time": null
  },
  "tracing_state": {
    "state": null,
    "detail": null,
    "remaining_time": null
  },
  "created": "2026-03-05T15:32:13",
  "duration": null,
  "file_url": "ac38014e-7b31-470d-b013-dc5318055adc.webp",
  "detection_results": {
    "run_id": "40fa5bb8-37b7-45d1-9647-14233e490c5f",
    "result": "alert",
    "start_date": "2026-03-11T07:58:59",
    "end_date": "2026-03-11T07:59:31",
    "extra_details": null,
    "details": [
      {
        "result_id": "c0065e39-5c63-4c65-a764-ddc24a77e1eb",
        "file_url": "ac38014e-7b31-470d-b013-dc5318055adc.webp",
        "name": "Synthetic",
        "result": "alert",
        "detail": "Synthetic: synthetic detection",
        "score": 0.7395417094230652,
        "decision": "Stable Diffusion XL",
        "color": "#FF0000",
        "info": "Detect synthetic images",
        "extra_details": null
      }
    ]
  },
  "tracing_results": null,
}

The exact content will depend on the type of file processed and the model applied.

Summary of the complete flow

1. A file is sent via an authenticated request.

2. The API returns a file_id.

3. An analysis operation is initiated on that file, specifying its file_id.

4. The API returns a run_id.

5. The status is checked periodically using that run_id.

6. When the status is OK or Alert, the results are retrieved.

This asynchronous model allows processing files of different sizes without blocking the API and guarantees scalability even under high load.