{ "openapi": "3.1.0", "info": { "title": "NUA Decision API", "version": "0.1.0", "description": "Evaluate JEV decision definitions against images and videos, or locate video events as scored time intervals.\n\n## Getting started\n\n1. Enter your account key in **Authentication**. Use the key supplied for your account; no signup is required.\n2. Upload a JPEG, PNG, MP4, MOV, or WebM file with **Upload media**. Copy its `id`.\n3. Pass that ID to an image decision, video decision, or timestamp request. You can submit while the file is preparing.\n4. If the job is pending, retrieve it with **Get a job**. Delete the file when finished.\n\nThe **Test Request** control sends requests to this API directly. Enter a key without the `Bearer` prefix; the request builder adds it. Credentials are not persisted across page reloads.\n\n```sh\ncurl https://docs.trynua.dev/v1/files \\\n -H \"Authorization: Bearer $NUA_API_KEY\" \\\n -F 'file=@video.mp4;type=video/mp4'\n```\n\n## JEV definitions\n\nEach named question has a `type` and `instructions`:\n\n| Type | Definition | Selected value |\n| --- | --- | --- |\n| `noul` | A yes/no condition | Boolean |\n| `choice` | An object mapping candidate IDs to descriptions | One of those candidate IDs |\n| `score` | An ordered array of level descriptions | Integer index, starting at zero |\n\nAnswers include a typed `value` and every candidate's probability. The highest-probability candidate is selected; declaration order breaks ties. Probabilities and temporal scores do not carry a calibration guarantee.\n\n## Jobs and retries\n\nRequests wait for up to 60 seconds by default. A terminal job returns HTTP `200`; a pending job returns `202` and a `Location` header. Set `background: true` to return immediately. Inspect `status` and `error` even after HTTP `200`.\n\nPolling a job never starts another run. An optional `Idempotency-Key` replays the same job for identical endpoint and body bytes. Changing the request with the same key returns `409`. Upload retries create another file.\n\n## Limits and retention\n\nImages: JPEG/PNG, 10 MB, 25 megapixels. Videos: MP4/MOV/WebM, 100 MB, two minutes, up to 4K. Audio is not analyzed. Video inference samples up to 128 frames at 65,536 pixels per frame.\n\nDefinitions allow 1\u201320 questions and 2\u201320 candidates per question. Each instruction or criterion may contain up to 4,000 characters; state is limited to 16,000 JSON bytes.\n\nEach account can retain two files and submit one executing job plus two queued jobs. Limits are 30 inference submissions, 10 uploads, 120 job status requests, and 240 total requests per minute. A `429` or `503` response includes `Retry-After`.\n\nFiles expire after ten idle minutes; results expire one hour after completion. Active jobs pin their media. Status polling does not extend file retention. Resources are held in RAM and service restarts can invalidate them.\n\n## Client packages\n\nThe clients support uploads, synchronous calls, background jobs, polling, cancellation, and JEV result validation. TypeScript infers answer keys and candidate values from literal definitions; Python validates returned values against the supplied definition.\n\n```sh\npip install https://docs.trynua.dev/clients/nua_decision-0.1.0-py3-none-any.whl\nnpm install https://docs.trynua.dev/clients/trynua-decision-0.1.0.tgz\n```\n\n[Download OpenAPI specification](/openapi.json) \u00b7 [Python client](/clients/nua_decision-0.1.0-py3-none-any.whl) \u00b7 [TypeScript client](/clients/trynua-decision-0.1.0.tgz)\n" }, "servers": [ { "url": "https://docs.trynua.dev/v1" } ], "security": [ { "apiKey": [] } ], "paths": { "/models": { "get": { "summary": "List models", "operationId": "listModels", "responses": { "200": { "description": "Model list", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "model" }, "owned_by": { "type": "string" }, "tasks": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "object", "owned_by", "tasks" ], "additionalProperties": false } } }, "required": [ "object", "data" ], "additionalProperties": false }, "example": { "object": "list", "data": [ { "id": "nua-decision-1", "object": "model", "owned_by": "nua", "tasks": [ "image_decision", "video_decision", "temporal" ] } ] } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Service" ] } }, "/health": { "get": { "summary": "Check readiness", "operationId": "health", "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "const": true } }, "required": [ "ready" ], "additionalProperties": false }, "example": { "ready": true } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Service" ] } }, "/files": { "post": { "summary": "Upload media", "operationId": "uploadFile", "description": "One file part only, with its MIME type. JPEG/PNG <=10 MB and 25 MP; MP4/MOV/WebM <=100 MB, two minutes, and 4K. Media expires after ten idle minutes; status polling does not extend retention.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ], "additionalProperties": false }, "encoding": { "file": { "contentType": "image/jpeg, image/png, video/mp4, video/quicktime, video/webm" } } } } }, "responses": { "202": { "description": "Accepted; preparation continues asynchronously", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" }, "example": { "id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "object": "file", "status": "preparing", "media_type": "video", "bytes": 1200000, "created_at": 1792785600, "expires_at": 1792786200 } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Files" ] } }, "/files/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "get": { "summary": "Get a file", "operationId": "getFile", "responses": { "200": { "description": "File status", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" }, "example": { "id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "object": "file", "status": "ready", "media_type": "video", "bytes": 1200000, "created_at": 1792785600, "expires_at": 1792786200, "metadata": { "width": 1920, "height": 1080, "duration_seconds": 10.01 } } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Files" ] }, "delete": { "summary": "Delete a file", "operationId": "deleteFile", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "file" }, "deleted": { "const": true } }, "required": [ "id", "object", "deleted" ], "additionalProperties": false }, "example": { "id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "object": "file", "deleted": true } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Files" ] } }, "/images/decisions": { "post": { "summary": "Evaluate image decisions", "operationId": "createImagesDecisions", "description": "Wait up to 60 seconds by default. background=true returns immediately. A pending call returns 202 and Location; retrieve the same immutable job. Video inputs require file_id. No inference streaming or automatic execution retries. Inline images use input.image_url with a JPEG/PNG base64 data URL. The sample is a generated 32\u00d732 solid-color PNG.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,80}$" }, "description": "Identical body bytes and endpoint return the same job until expiry. A different request with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest" }, "examples": { "uploaded_file": { "summary": "Use an uploaded file", "value": { "model": "nua-decision-1", "input": { "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "questions": { "person_present": { "type": "noul", "instructions": "A person is visible." }, "activity": { "type": "choice", "instructions": "Select the activity.", "criteria": { "walking": "Walking", "sitting": "Sitting" } }, "crowding": { "type": "score", "instructions": "Rate crowding.", "criteria": [ "No people", "One person", "Several people" ] } } } }, "inline_image": { "summary": "Try a sample inline PNG", "value": { "model": "nua-decision-1", "input": { "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAKklEQVR4nO3NQQkAAAgEsItuFKMYzRQ+hMH+S/WcikAgEAgEAoFAIPgSLLY3gGqjMrYlAAAAAElFTkSuQmCC" }, "questions": { "person_present": { "type": "noul", "instructions": "A person is visible." } } } } } } } }, "responses": { "200": { "description": "Terminal result", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "completed", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": 1792789200, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "metadata": { "model_revision": "5693d3a9ec02b4e868fd05d1395c57a751f9af51", "sampled_frame_count": 1 }, "answers": { "person_present": { "type": "noul", "value": true, "probabilities": { "true": 0.91, "false": 0.09 } }, "activity": { "type": "choice", "value": "walking", "probabilities": { "walking": 0.8, "sitting": 0.2 } }, "crowding": { "type": "score", "value": 1, "probabilities": { "0": 0.1, "1": 0.7, "2": 0.2 } } } } } } }, "202": { "description": "Pending job", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "queued", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": null, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Images" ] } }, "/videos/decisions": { "post": { "summary": "Evaluate video decisions", "operationId": "createVideosDecisions", "description": "Wait up to 60 seconds by default. background=true returns immediately. A pending call returns 202 and Location; retrieve the same immutable job. Video inputs require file_id. No inference streaming or automatic execution retries.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,80}$" }, "description": "Identical body bytes and endpoint return the same job until expiry. A different request with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionRequest", "description": "input must reference an uploaded video file_id; inline images are not accepted." }, "examples": { "uploaded_file": { "summary": "Use an uploaded file", "value": { "model": "nua-decision-1", "input": { "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "questions": { "person_present": { "type": "noul", "instructions": "A person is visible." }, "activity": { "type": "choice", "instructions": "Select the activity.", "criteria": { "walking": "Walking", "sitting": "Sitting" } }, "crowding": { "type": "score", "instructions": "Rate crowding.", "criteria": [ "No people", "One person", "Several people" ] } } } } } } } }, "responses": { "200": { "description": "Terminal result", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "completed", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": 1792789200, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "metadata": { "model_revision": "5693d3a9ec02b4e868fd05d1395c57a751f9af51", "sampled_frame_count": 128 }, "answers": { "person_present": { "type": "noul", "value": true, "probabilities": { "true": 0.91, "false": 0.09 } }, "activity": { "type": "choice", "value": "walking", "probabilities": { "walking": 0.8, "sitting": 0.2 } }, "crowding": { "type": "score", "value": 1, "probabilities": { "0": 0.1, "1": 0.7, "2": 0.2 } } } } } } }, "202": { "description": "Pending job", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "queued", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": null, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Videos" ] } }, "/videos/timestamps": { "post": { "summary": "Find event timestamps", "operationId": "createVideosTimestamps", "description": "Wait up to 60 seconds by default. background=true returns immediately. A pending call returns 202 and Location; retrieve the same immutable job. Video inputs require file_id. No inference streaming or automatic execution retries.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,80}$" }, "description": "Identical body bytes and endpoint return the same job until expiry. A different request with the same key returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimestampRequest", "description": "input must reference an uploaded video file_id; inline images are not accepted." }, "examples": { "uploaded_file": { "summary": "Use an uploaded file", "value": { "model": "nua-decision-1", "input": { "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" }, "query": "A person opens the door.", "background": true } } } } } }, "responses": { "200": { "description": "Terminal result", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "timestamps", "status": "completed", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": 1792789200, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "metadata": { "model_revision": "5693d3a9ec02b4e868fd05d1395c57a751f9af51", "sampled_frame_count": 128 }, "intervals": [ { "start_seconds": 1.2, "end_seconds": 3.4, "score": 0.8 } ] } } } }, "202": { "description": "Pending job", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "timestamps", "status": "queued", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": null, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Videos" ] } }, "/jobs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ], "get": { "summary": "Get a job", "operationId": "getJob", "responses": { "200": { "description": "Current job state", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "completed_decision": { "summary": "Completed decision", "value": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "completed", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": 1792789200, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "metadata": { "model_revision": "5693d3a9ec02b4e868fd05d1395c57a751f9af51", "sampled_frame_count": 128 }, "answers": { "person_present": { "type": "noul", "value": true, "probabilities": { "true": 0.91, "false": 0.09 } }, "activity": { "type": "choice", "value": "walking", "probabilities": { "walking": 0.8, "sitting": 0.2 } }, "crowding": { "type": "score", "value": 1, "probabilities": { "0": 0.1, "1": 0.7, "2": 0.2 } } } } }, "completed_timestamps": { "summary": "Completed timestamps", "value": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "timestamps", "status": "completed", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": 1792789200, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "metadata": { "model_revision": "5693d3a9ec02b4e868fd05d1395c57a751f9af51", "sampled_frame_count": 128 }, "intervals": [ { "start_seconds": 1.2, "end_seconds": 3.4, "score": 0.8 } ] } }, "queued": { "summary": "Queued job", "value": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "queued", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": null, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Jobs" ] } }, "/jobs/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" } ], "post": { "summary": "Cancel a job", "operationId": "cancelJob", "description": "Queued jobs cancel immediately. Running execution enters cancelling and retains memory until it returns.", "responses": { "200": { "description": "Current job state", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "job_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "object": "decision", "status": "cancelling", "model": "nua-decision-1", "created_at": 1792785600, "expires_at": null, "file_id": "file_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } } } }, "400": { "description": "Invalid request", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid request", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "401": { "description": "Invalid API key", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid API key", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } } } }, "404": { "description": "Resource missing, expired, or owned by another account", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Resource missing, expired, or owned by another account", "type": "invalid_request_error", "param": null, "code": "not_found" } } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Idempotency conflict", "type": "invalid_request_error", "param": null, "code": "idempotency_conflict" } } } } }, "413": { "description": "Request or media exceeds limits", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Request or media exceeds limits", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "415": { "description": "Unsupported media type", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Unsupported media type", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "422": { "description": "Invalid definition or input", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Invalid definition or input", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } } } }, "429": { "description": "Rate or capacity limit", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Rate or capacity limit", "type": "rate_limit_error", "param": null, "code": "capacity_exceeded" } } } } }, "500": { "description": "Internal error", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Internal error", "type": "server_error", "param": null, "code": "internal_error" } } } } }, "503": { "description": "Compute unavailable", "headers": { "X-Request-ID": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "message": "Compute unavailable", "type": "server_error", "param": null, "code": "compute_unavailable" } } } } } }, "tags": [ "Jobs" ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Enter the account key supplied to you. Requests use `Authorization: Bearer `. Keys sharing an account ID share resources and quotas." } }, "schemas": { "Noul": { "type": "object", "properties": { "type": { "const": "noul" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "type", "instructions" ], "additionalProperties": false, "example": { "type": "noul", "instructions": "A person is visible." } }, "Choice": { "type": "object", "properties": { "type": { "const": "choice" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 4000 }, "criteria": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 4000 }, "minProperties": 2, "maxProperties": 20, "description": "Candidate declaration order breaks probability ties. Duplicate keys are rejected." } }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": false, "example": { "type": "choice", "instructions": "Select the activity.", "criteria": { "walking": "Walking", "sitting": "Sitting" } } }, "Score": { "type": "object", "properties": { "type": { "const": "score" }, "instructions": { "type": "string", "minLength": 1, "maxLength": 4000 }, "criteria": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 4000 }, "minItems": 2, "maxItems": 20 } }, "required": [ "type", "instructions", "criteria" ], "additionalProperties": false, "example": { "type": "score", "instructions": "Rate crowding.", "criteria": [ "No people", "One person", "Several people" ] } }, "Question": { "oneOf": [ { "$ref": "#/components/schemas/Noul" }, { "$ref": "#/components/schemas/Choice" }, { "$ref": "#/components/schemas/Score" } ], "discriminator": { "propertyName": "type" } }, "Questions": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "additionalProperties": { "$ref": "#/components/schemas/Question" }, "minProperties": 1, "maxProperties": 20, "example": { "person_present": { "type": "noul", "instructions": "A person is visible." }, "activity": { "type": "choice", "instructions": "Select the activity.", "criteria": { "walking": "Walking", "sitting": "Sitting" } }, "crowding": { "type": "score", "instructions": "Rate crowding.", "criteria": [ "No people", "One person", "Several people" ] } } }, "Input": { "oneOf": [ { "type": "object", "properties": { "file_id": { "type": "string", "pattern": "^file_[a-f0-9]{32}$" } }, "required": [ "file_id" ], "additionalProperties": false }, { "type": "object", "properties": { "image_url": { "type": "string", "description": "JPEG or PNG base64 data URL, up to 10 MB decoded; image endpoints only." } }, "required": [ "image_url" ], "additionalProperties": false } ] }, "DecisionRequest": { "type": "object", "properties": { "model": { "const": "nua-decision-1" }, "input": { "$ref": "#/components/schemas/Input" }, "background": { "type": "boolean", "default": false }, "questions": { "$ref": "#/components/schemas/Questions" }, "state": { "type": "object", "additionalProperties": true, "description": "At most 16,000 JSON bytes." } }, "required": [ "model", "input", "questions" ], "additionalProperties": false }, "TimestampRequest": { "type": "object", "properties": { "model": { "const": "nua-decision-1" }, "input": { "$ref": "#/components/schemas/Input" }, "background": { "type": "boolean", "default": false }, "query": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "model", "input", "query" ], "additionalProperties": false }, "NoulAnswer": { "type": "object", "properties": { "type": { "const": "noul" }, "value": { "type": "boolean" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "minProperties": 2, "maxProperties": 20 } }, "required": [ "type", "value", "probabilities" ], "additionalProperties": false, "description": "Validated against the submitted definition. Value is argmax; declaration order breaks ties." }, "ChoiceAnswer": { "type": "object", "properties": { "type": { "const": "choice" }, "value": { "type": "string" }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "minProperties": 2, "maxProperties": 20 } }, "required": [ "type", "value", "probabilities" ], "additionalProperties": false, "description": "Validated against the submitted definition. Value is argmax; declaration order breaks ties." }, "ScoreAnswer": { "type": "object", "properties": { "type": { "const": "score" }, "value": { "type": "integer", "minimum": 0, "maximum": 19 }, "probabilities": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }, "minProperties": 2, "maxProperties": 20 } }, "required": [ "type", "value", "probabilities" ], "additionalProperties": false, "description": "Validated against the submitted definition. Value is argmax; declaration order breaks ties." }, "Answer": { "oneOf": [ { "$ref": "#/components/schemas/NoulAnswer" }, { "$ref": "#/components/schemas/ChoiceAnswer" }, { "$ref": "#/components/schemas/ScoreAnswer" } ], "discriminator": { "propertyName": "type" } }, "Interval": { "type": "object", "properties": { "start_seconds": { "type": "number", "minimum": 0 }, "end_seconds": { "type": "number", "exclusiveMinimum": 0 }, "score": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "start_seconds", "end_seconds", "score" ], "additionalProperties": false, "description": "start < end <= original video duration; scores are not a calibrated confidence guarantee." }, "APIError": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "code": { "type": "string" } }, "required": [ "message", "type", "param", "code" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/APIError" } }, "required": [ "error" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^job_[a-f0-9]{32}$" }, "object": { "enum": [ "decision", "timestamps" ] }, "status": { "enum": [ "preparing", "queued", "running", "cancelling", "completed", "failed", "cancelled" ] }, "model": { "type": "string" }, "created_at": { "type": "integer" }, "expires_at": { "type": [ "integer", "null" ] }, "file_id": { "type": "string" }, "answers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Answer" } }, "intervals": { "type": "array", "items": { "$ref": "#/components/schemas/Interval" } }, "metadata": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/APIError" } }, "required": [ "id", "object", "status", "model", "created_at", "expires_at", "file_id" ], "additionalProperties": false, "description": "Completed decision jobs have answers; completed timestamp jobs have intervals. Other states omit result fields. Each job is independent of subsequent calls. Completed results expire after one hour." }, "File": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^file_[a-f0-9]{32}$" }, "object": { "const": "file" }, "status": { "enum": [ "uploading", "preparing", "ready", "failed" ] }, "media_type": { "enum": [ "image", "video" ] }, "bytes": { "type": "integer" }, "created_at": { "type": "integer" }, "expires_at": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "error": { "$ref": "#/components/schemas/APIError" } }, "required": [ "id", "object", "status", "media_type", "bytes", "created_at", "expires_at" ], "additionalProperties": false } } }, "tags": [ { "name": "Images", "description": "Evaluate JEV definitions against one native image. Use an uploaded file ID or an inline base64 data URL." }, { "name": "Videos", "description": "Evaluate a whole video or find event intervals. Reuse an uploaded file across calls." }, { "name": "Files", "description": "Upload, inspect and release account-owned media." }, { "name": "Jobs", "description": "Retrieve immutable results or cancel work." }, { "name": "Service", "description": "List models and check readiness." } ] }