Introduction Quickstart Authentication MCP ServerNEW API Reference Available Apps

API Reference

Complete reference for all API endpoints.

Base URL

https://app.neuroviz.ai/api/v1

POST/api/v1/run

Submit a new image generation job. The job will be processed asynchronously and results will be sent to your webhook URL.

Request Headers

AuthorizationstringrequiredBearer token with your API key

Content-TypestringrequiredMust be application/json

Request Body

app_idstringrequiredThe unique identifier of the app to run

parametersobjectrequiredApp-specific parameters (see Available Apps for each app's parameters)

webhook_urlstringrequiredURL where results will be sent when processing completes

Example Request

Request Body

{
  "app_id": "your-app-id",
  "parameters": {
    "image": "https://example.com/your-image.jpg",
    "style": "natural"
  },
  "webhook_url": "https://your-server.com/webhook"
}

Response

200Success

Success Response

{
  "run_id": "abc123-def456-ghi789"
}

401Unauthorized — Invalid or missing API key

400Bad Request — Invalid request body or missing required parameters

402Payment Required — Insufficient credits to run this app

PARAMSRetoucher output settings

The jewelry retoucher apps (Rescue, Precision) accept an optional set of post-processing parameters in the parameters object of POST /run. All of them are optional — omit them and the model output is returned unchanged.

Background & Shadow

bg_modestringoptional"off" (default), "solid" or "transparent". "solid" removes the background and composites the item on bg_color; "transparent" removes it and saves a PNG with alpha. Either non-"off" mode adds +3 credits to the run.

bg_colorstringoptionalHex color for the solid background (e.g. "#ffffff"). Only used when bg_mode = "solid".

bg_shadowbooleanoptionalAdds a natural soft contact shadow under the item on the solid background. Only applies when bg_mode = "solid". Free — no extra credits.

Shadow fine-tuning (optional)

API-key accounts can tune the shadow per run. When omitted, your saved User Settings shadow defaults apply. Out-of-range values are clamped, and the parameters are ignored unless bg_mode = "solid" with bg_shadow = true.

shadow_intensitynumberoptionalShadow darkness/opacity multiplier. Range 0.1–3, default 1.

shadow_sizenumberoptionalShadow footprint size multiplier. Range 0.2–3, default 1.

shadow_softnessnumberoptionalShadow edge blur multiplier. Range 0.2–3, default 1.

shadow_distancenumberoptionalShadow offset from the item as a fraction of its size. Range 0–0.2, default 0.

Framing / crop control

framing_enabledbooleanoptionalCrops the item precisely and re-frames it with per-side padding. The output keeps the selected aspect ratio and the item is never scaled. Free — no extra credits.

framing_pad_topnumberoptionalTop padding as a percent of the item's longest side. Range 0–100, default 15.

framing_pad_rightnumberoptionalRight padding, percent of the item's longest side. Range 0–100, default 15.

framing_pad_bottomnumberoptionalBottom padding, percent of the item's longest side. Range 0–100, default 15.

framing_pad_leftnumberoptionalLeft padding, percent of the item's longest side. Range 0–100, default 15.

De-banding

debandingbooleanoptionalRemoves the subtle wave-like banding that can appear on polished metal and smooth gradients. Adds +1 credit. The run returns TWO outputs: the de-banded image on output_url and the untouched original in extra_outputs — see the run status endpoint below.

Two outputs when de-banding is on

A run with debanding = true keeps the untouched original next to the de-banded result. Poll GET /runs/{run_id}: output_url is the de-banded image (primary_label = "De-Banded"), and extra_outputs lists the "Original" with its own presigned URL.

WEBHOOKYour Webhook URL

When processing completes (success or failure), we send a POST request to your webhook URL with the results.

Webhook Payload

run_idstringoptionalThe ID of the run that was submitted

statusstringoptionalEither "SUCCESS" or "FAILURE"

output_urlstringoptionalURL to download the generated image (only on success)

thumbnailstringoptionalURL to a smaller thumbnail version (only on success)

errorstringoptionalError message (only on failure)

Success Example

Webhook Payload (Success)

{
  "run_id": "abc123-def456-ghi789",
  "status": "SUCCESS",
  "output_url": "https://cdn.neuroviz.ai/outputs/result.png",
  "thumbnail": "https://cdn.neuroviz.ai/outputs/result_thumb.png"
}

Failure Example

Webhook Payload (Failure)

{
  "run_id": "abc123-def456-ghi789",
  "status": "FAILURE",
  "error": "Invalid image URL or image could not be downloaded"
}

GET/api/v1/runs/{run_id}

Get the status and output of a single run. Use this to poll for results as an alternative to webhooks, or to retrieve the output URL after your webhook receives a success notification.

Path Parameters

run_idstringrequiredThe run ID returned from POST /api/v1/run

Response Fields

run_idstringoptionalThe unique run identifier

app_idstringoptionalThe app that was run

app_titlestringoptionalHuman-readable app name

statusstringoptionalIN_QUEUE, IN_PROGRESS, SUCCESS, or FAILED

createdstringoptionalISO 8601 timestamp when the run was submitted

completedstringoptionalISO 8601 timestamp when processing finished (only if completed)

credits_chargedintegeroptionalNumber of credits charged for this run

output_urlstringoptionalSigned URL to download the output (only if SUCCESS, expires in 15 minutes)

errorstringoptionalError message (only if FAILED)

is_videobooleanoptionalWhether the output is a video file

extra_outputsarrayoptionalSecondary stored outputs, present only when a SUCCESS run produced more than one file (e.g. the untouched original kept beside a de-banded retoucher output). Each entry carries label, slug, format and its own presigned url with the same 15-minute expiry as output_url.

primary_labelstringoptionalWhat output_url contains when extra_outputs is present (e.g. "De-Banded").

Success Example (completed run)

Response (200)

{
  "run_id": "abc123-def456-ghi789",
  "app_id": "your-app-id",
  "app_title": "Virtual Try On Bracelet",
  "status": "SUCCESS",
  "created": "2026-04-04T19:20:00Z",
  "completed": "2026-04-04T19:21:30Z",
  "credits_charged": 20,
  "output_url": "https://signed-s3-url...",
  "is_video": false
}

Two-Output Example (De-banding enabled)

Retoucher runs submitted with debanding = true keep the untouched original beside the de-banded primary — both downloadable via their own presigned URLs.

Response (200)

{
  "run_id": "abc123-def456-ghi789",
  "app_id": "your-app-id",
  "app_title": "Jewelry Retoucher Rescue",
  "status": "SUCCESS",
  "created": "2026-08-06T19:20:00Z",
  "completed": "2026-08-06T19:21:30Z",
  "credits_charged": 6,
  "output_url": "https://signed-s3-url...",
  "is_video": false,
  "primary_label": "De-Banded",
  "extra_outputs": [
    {
      "label": "Original",
      "slug": "original",
      "format": "png",
      "url": "https://signed-s3-url..."
    }
  ]
}

In Progress Example

Response (200)

{
  "run_id": "abc123-def456-ghi789",
  "app_id": "your-app-id",
  "app_title": "Virtual Try On Bracelet",
  "status": "IN_PROGRESS",
  "created": "2026-04-04T19:20:00Z",
  "credits_charged": 20,
  "is_video": false
}

404Not Found — Run not found or does not belong to your account

GET/api/v1/runs

List your recent runs with pagination. Useful for reviewing history and finding run IDs.

Query Parameters

pageintegeroptionalPage number, starting from 1 (default: 1)

limitintegeroptionalResults per page, max 50 (default: 20)

statusstringoptionalFilter by status: SUCCESS, FAILED, IN_QUEUE, IN_PROGRESS, or all (default: all)

Response

Response (200)

{
  "runs": [
    {
      "run_id": "abc123-def456-ghi789",
      "app_id": "your-app-id",
      "app_title": "Virtual Try On Bracelet",
      "status": "SUCCESS",
      "created": "2026-04-04T19:20:00Z",
      "credits_charged": 20
    }
  ],
  "total": 142,
  "page": 1,
  "has_more": true
}

GET/api/v1/balance

Check your current credit balance. Use this to verify you have enough credits before submitting runs.

Response Fields

total_creditsintegeroptionalTotal available credits (subscription + other)

subscription_creditsintegeroptionalCredits from your subscription plan

other_creditsintegeroptionalCredits from add-on purchases

subscriptionstringoptionalYour subscription tier name

credits_expirestringoptionalISO 8601 expiration date (null for Pro members)

Example Response

Response (200)

{
  "total_credits": 1234,
  "subscription_credits": 1000,
  "other_credits": 234,
  "subscription": "Pro",
  "credits_expire": "2027-04-04T00:00:00Z"
}

GET/api/v1/runs/{run_id}/download

Get a signed download URL for a completed run's output. The URL expires after 15 minutes.

Path Parameters

run_idstringrequiredThe run ID of a completed (SUCCESS) run

Response Fields

download_urlstringoptionalSigned URL to download the output file

filenamestringoptionalSuggested filename (e.g., neuroviz_output.png)

expires_inintegeroptionalURL expiry time in seconds (900 = 15 minutes)

Example Response

Response (200)

{
  "download_url": "https://signed-s3-url...",
  "filename": "neuroviz_output.png",
  "expires_in": 900
}

400Bad Request — Run has not completed successfully yet

404Not Found — Run not found or does not belong to your account

GET/api/v1/apps

List all apps available for API access. This endpoint does not require authentication.

Response

Returns an array of app objects with their parameters. See Available Apps for details.

No authentication required

This is the only endpoint that can be called without a Bearer token.