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

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

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
}

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.