Create a new analysis

POST

/v1/analysis

const url = 'https://api.neuramancer.dev/v1/analysis';
const options = {
  method: 'POST',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"name":"example","tags":["example"],"comment":"example","type":"image","input":{"format":"jpg","storageUrls":{"type":"azure","objectKey":"example","putUrl":"example","getUrl":"example","deleteUrl":"example","expiresAt":"2026-04-15T12:00:00Z"},"options":{"model":"nais-image-latest","decisionStrategy":"default","tier":"forensicReporting","seed":1337},"version":"v1","width":1,"height":1,"filename":"example"},"tenantName":"example","projectId":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.neuramancer.dev/v1/analysis \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "tags": [ "example" ], "comment": "example", "type": "image", "input": { "format": "jpg", "storageUrls": { "type": "azure", "objectKey": "example", "putUrl": "example", "getUrl": "example", "deleteUrl": "example", "expiresAt": "2026-04-15T12:00:00Z" }, "options": { "model": "nais-image-latest", "decisionStrategy": "default", "tier": "forensicReporting", "seed": 1337 }, "version": "v1", "width": 1, "height": 1, "filename": "example" }, "tenantName": "example", "projectId": "example" }'

Creates an analysis record and returns it. Requires authentication (API key or user JWT).

Authorizations

ApiKeyAuth
BearerAuth

Request Body^required

application/json

Request payload to create an analysis

object

name

required

string

tags

Array<string>

comment

string

type

required

string

Allowed values: image

input

required

One of:

object

object

format

required

string

Allowed values: jpg png

storageUrls

S3 storage URLs for input file

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

options

required

object

model

Inference model identifier

string

default: nais-image-latest

Example

nais-image-latest

decisionStrategy

The decisionStrategy parameter controls decision strategy the “uncertain” / “abstain” ratio. It doesn’t change the classification of real vs. fake.

string

default: default

Allowed values: default pedantic relaxed

tier

Analysis tier. Defaults to ‘flagging’ which returns only the simple flag (resultClass, resultSubClasses, decisionStrategy). Use ‘forensicReporting’ to receive detailed predictions, uncertainties, similarities, text content, heatmaps, and localized report access.

string

default: flagging

Allowed values: forensicReporting flagging

seed

Seed for random number generation in inference. A fixed seed (default 1337) produces stable, reproducible results due to seeded random behaviour. Varying the seed introduces non-determinism for more probabilistic results.

integer

default: 1337

Example

version

required

string

Allowed values: v1

format

required

string

Allowed values: jpg png

width

required

Image width in pixels (must be >64 and ≤4096)

integer

> 64 <= 4096

height

required

Image height in pixels (must be >64 and ≤4096)

integer

> 64 <= 4096

filename

required

string

tenantName

required

string

projectId

string

nullable

Responses

200

Analysis created successfully

application/json

object

success

boolean

data

Array<object>

object

Database ObjectId (string)

string

tenantId

string

projectId

string

nullable

name

string

storageType

Blob storage type

string

Allowed values: azure s3

type

string

Allowed values: image

input

One of:

object

object

format

required

string

Allowed values: jpg png

storageUrls

S3 storage URLs for input file

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

options

required

object

model

Inference model identifier

string

default: nais-image-latest

decisionStrategy

The decisionStrategy parameter controls decision strategy the “uncertain” / “abstain” ratio. It doesn’t change the classification of real vs. fake.

string

default: default

Allowed values: default pedantic relaxed

tier

string

default: flagging

Allowed values: forensicReporting flagging

seed

integer

default: 1337

version

required

string

Allowed values: v1

format

required

string

Allowed values: jpg png

width

required

Image width in pixels (must be >64 and ≤4096)

integer

> 64 <= 4096

height

required

Image height in pixels (must be >64 and ≤4096)

integer

> 64 <= 4096

filename

required

string

inferenceStatus

One of:

object

object

status

string

Allowed values: pending processing completed failed

statusMessage

string

retryCount

integer

processingStartTime

string format: date-time

nullable

processingFinishTime

string format: date-time

nullable

result

Inference result for an image analysis. For ‘flagging’ tier analyses, only resultClass and resultSubClasses are populated; all other fields are null. All fields are populated for ‘forensicReporting’ tier.

object

resultClass

Final classification: 0 real | 1 fake | 2 abstain | 3 uncertain

number

resultSubClasses

Sub-classification: 0 ai-generated | 1 ai-manipulated | 2 manipulated (empty set is allowed)

Array<number>

predictions

Per-class prediction probabilities.

object

real

Probability the image is authentic (0.0 - 1.0)

number

fake

Probability the image is synthetic/manipulated (0.0 - 1.0)

number

compression

Compression artifact score (0.0 - 1.0)

number

classUncertainties

Per-class uncertainty estimates (Monte-Carlo derived).

object

real

Uncertainty measure for the real classification

number

fake

Uncertainty measure for the fake classification

number

compression

Uncertainty measure for compression detection

number

classSimilarities

Per-class similarity scores.

object

realCompressed

Similarity score between real and compressed features

number

fakeCompressed

Similarity score between fake and compressed features

number

anomaly

Anomaly detection results (score, numCluster, giniCoeff). Null on error or for ‘flagging’ tier analyses.

object

score

Overall anomaly score in the range 0.0 - 1.0.

number

nullable

numCluster

Number of detected anomaly clusters (integer).

number

nullable

giniCoeff

Gini coefficient of the spatial anomaly distribution (0.0 - 1.0).

number

nullable

heatmaps

Heatmap visualizations. Null if no heatmaps were generated, on error, or for ‘flagging’ tier analyses.

object

realHeatmapStorageUrls

Storage URLs for the real/authenticity heatmap

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

fakeHeatmapStorageUrls

Storage URLs for the fake/synthetic heatmap

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

compressionHeatmapStorageUrls

Storage URLs for the compression heatmap

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

anomalyHeatmapStorageUrls

Storage URLs for the anomaly heatmap

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

report

Localized report outputs keyed by language. Only available for ‘forensicReporting’ tier; null otherwise, if not yet generated, or on error.

object

Localized report output for a single supported language.

object

pdfStorageUrls

Storage URLs for the localized PDF report.

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

summary

Short localized summary of the forensic verdict.

string

forensic

Localized detailed forensic explanation.

string

heatmapIntro

Localized introductory text for the heatmaps section.

string

heatmap

Localized explanatory text per heatmap type (real, fake, compressed, anomaly).

object

real

string

fake

string

compressed

string

anomaly

string

conclusion

Localized concluding verdict.

string

Localized report output for a single supported language.

object

pdfStorageUrls

Storage URLs for the localized PDF report.

object

type

required

Storage backend type

string

Allowed values: azure s3

objectKey

required

S3 object key used to regenerate presigned URLs on expiry

string

putUrl

required

Presigned URL for uploading

string

getUrl

required

Presigned URL for downloading

string

deleteUrl

required

Presigned URL for deletion

string

expiresAt

required

ISO date string when the URLs expire

string format: date-time

summary

Short localized summary of the forensic verdict.

string

forensic

Localized detailed forensic explanation.

string

heatmapIntro

Localized introductory text for the heatmaps section.

string

heatmap

Localized explanatory text per heatmap type (real, fake, compressed, anomaly).

object

real

string

fake

string

compressed

string

anomaly

string

conclusion

Localized concluding verdict.

string

comment

string

tags

Array<string>

createdDate

string format: date-time

updatedDate

string format: date-time

nullable

createdByUserId

Immutable creator identifier. Stores the MongoDB user ObjectId string for user-authenticated requests, the API key UUID for API-key requests, or null for system-created records.

string

nullable

lastChangedByUserType

Actor type that last changed the analysis (for example user or api).

string

nullable

lastChangedByUserId

Identifier of the actor that last changed the analysis. Stores the MongoDB user ObjectId string for user-authenticated requests, the API key UUID for API-key requests, or null for system updates.

string

nullable

lastChangedByUserName

Projected display name of the user referenced by lastChangedByUserId. Populated on analysis read responses when the last actor type is user and the corresponding user record has a name; otherwise null.

string

nullable

deletedDate

string format: date-time

nullable

tierUpgradedFrom

Original tier before a tier upgrade via POST /v1/analysis/retry (e.g. flagging). Null if no upgrade has occurred. Downgrades are not permitted.

string

nullable

Allowed values: flagging forensicReporting

tierUpgradedAt

Timestamp of when the tier upgrade occurred. Null if no upgrade has occurred.

string format: date-time

nullable

Example

{
  "success": true,
  "data": [
    {
      "storageType": "azure",
      "type": "image",
      "input": {
        "format": "jpg",
        "storageUrls": {
          "type": "azure"
        },
        "options": {
          "model": "nais-image-latest",
          "decisionStrategy": "default",
          "tier": "forensicReporting",
          "seed": 1337
        },
        "version": "v1"
      },
      "inferenceStatus": {
        "status": "pending",
        "result": {
          "heatmaps": {
            "realHeatmapStorageUrls": {
              "type": "azure"
            },
            "fakeHeatmapStorageUrls": {
              "type": "azure"
            },
            "compressionHeatmapStorageUrls": {
              "type": "azure"
            },
            "anomalyHeatmapStorageUrls": {
              "type": "azure"
            }
          },
          "report": {
            "de": {
              "pdfStorageUrls": {
                "type": "azure"
              }
            },
            "en": {
              "pdfStorageUrls": {
                "type": "azure"
              }
            }
          }
        }
      },
      "tierUpgradedFrom": "flagging"
    }
  ]
}

400

Invalid request

application/json

Standardized error response following the APIResponse schema.

object

success

required

boolean

message

required

string

Example

{
  "success": false,
  "message": "Bad request"
}

404

Tenant not found

application/json

Standardized error response following the APIResponse schema.

object

success

required

boolean

message

required

string

Example

{
  "success": false,
  "message": "Bad request"
}

Create a new analysis

Authorizations

Request Bodyrequired

Example

Example

Responses

200

Example

400

Example

404

Example

Request Body^required