Process API¶

Send a JPEG snapshot and get a print-quality score, warning and pause suggestions, and the minimum and recommended delays before your next snapshot.

Start with the Create Context API. Using the same context lets Gadget consider results from earlier snapshots when checking how the print is progressing.

HTTP Request¶

Use the full ProcessRequestUrl returned by the Create Context API, exactly as returned. It already includes the context ID. See retries and fallback URLs if that server is unavailable.

POST https://<your-process-host>.octoeverywhere.com/api/gadget/v1/process/{ID}

Headers¶

Path Parameters¶

Request Body¶

Send exactly one image file in a multipart/form-data POST body; JPEG is recommended. The image file can be up to 6 MiB (6,291,456 bytes), excluding multipart overhead. The field name and filename can be anything; this example uses image and print.jpg.

Example Request¶

Replace the URL placeholder with the full ProcessRequestUrl, add your key, and point curl at your JPEG file:

PROCESS_REQUEST_URL='PASTE_FULL_ProcessRequestUrl_HERE'

curl --request POST "$PROCESS_REQUEST_URL" \
    -H 'X-API-Key: prod_YOUR_API_KEY' \
    -F '[email protected]'

Let curl set Content-Type so it includes the required multipart boundary. For Python, the standalone HTTP example shows the upload, timing, and error handling using requests.

Successful Response¶

{
    "NextProcessIntervalSec": {
        "Minimum": 5,
        "Recommended": 20
    },
    "FasterInspectionSuggested": false,
    "PrintQuality": 8,
    "WarningSuggested": false,
    "PauseSuggested": false,
    "Score": 5
}

Which fields should I use?¶

The warning and pause flags are recommendations. Your software sends the warning or pauses the printer.

Response Details¶

NextProcessIntervalSec¶

Use NextProcessIntervalSec.Recommended as the default inspection interval, taking the value from the latest Process API response. You can inspect faster than recommended, provided you wait at least NextProcessIntervalSec.Minimum seconds between calls.

For a custom interval, wait max(your_configured_interval, NextProcessIntervalSec.Minimum) seconds before sending the next snapshot. A fixed interval is supported for predictable usage. You can optionally follow FasterInspectionSuggested to temporarily use the recommended interval when Gadget detects a possible issue. If no custom interval is configured, use NextProcessIntervalSec.Recommended.

All print-hour pricing uses a 20-second interval: 180 inspection calls equal one print hour. Billing is based on inspection calls, so inspecting faster uses more calls, consumes the free allowance sooner, and increases paid usage costs. A 5-second interval uses four times as many calls per actual hour of printing as a 20-second interval.

FasterInspectionSuggested¶

FasterInspectionSuggested is an optional timing hint for apps that normally use a fixed inspection interval. You can ignore it and keep your configured interval for predictable usage, or use it to follow the same signal that makes OctoEverywhere inspect more frequently internally. Apps that already follow NextProcessIntervalSec.Recommended need no extra timing logic.

The flag is normally false and is expected to stay off roughly 99% of the time during normal printing; this is an expectation, not a guaranteed percentage. Gadget sets it to true only when it has strong evidence of a possible issue and wants faster snapshots to build confidence before recommending a warning or pause. It covers possible warning and pause conditions, and can still be true on the response that first sets WarningSuggested or PauseSuggested.

To opt in, choose your next delay after each successful response:

• If FasterInspectionSuggested is true, use the latest NextProcessIntervalSec.Recommended.
• If it is false or missing, return to your configured interval. Treating a missing field as false keeps clients compatible with older responses.
• Always wait at least the latest NextProcessIntervalSec.Minimum, currently 5 seconds. This flag never permits calls below the minimum.

For example, with a configured interval in seconds:

intervals = response["NextProcessIntervalSec"]
next_delay = configured_interval
if response.get("FasterInspectionSuggested", False):
    next_delay = intervals["Recommended"]
next_delay = max(next_delay, intervals["Minimum"])

Use WarningSuggested and PauseSuggested to decide when to act; FasterInspectionSuggested only controls timing. Temporarily shortening the interval makes more inspection calls, which can consume the free allowance sooner and increase paid usage costs.

PrintQuality¶

PrintQuality ranges from 1 to 10, where 10 is perfect print quality.

Use it on printer displays, dashboards, or anywhere you show print status. For warnings and pause actions, use WarningSuggested and PauseSuggested instead of acting on this score alone.

WarningSuggested¶

WarningSuggested is true when Gadget is confident enough to recommend warning the user about a possible print issue.

Adjust the required confidence with WarningConfidenceLevel when creating the context. Gadget considers several signals over time, so PrintQuality may stay in the 1-3 range for 30-80 seconds before this flag becomes true.

PauseSuggested¶

PauseSuggested is true when Gadget is confident enough to recommend pausing a print that has probably failed.

The required confidence can be adjusted with PauseConfidenceLevel when creating the context. Because pausing a print is intrusive, the model waits for high confidence before raising this flag. PrintQuality may stay in the 1-3 range for 60-120 seconds before PauseSuggested becomes true.

Score¶

Most apps can ignore Score. It's the raw model score, from 0 for a perfect print to 100 for a strong probability of failure.

Use it for custom analysis, such as smoothing or combining results. Use the quality score and suggestion flags for user-facing status and actions.

Error Response¶

If the API does not return a 200 response, it returns an HTTP error code with a common JSON error object.

{
    "ErrorType": "OE_IMAGE_DECODE_FAILED",
    "ErrorDetails": "The uploaded image could not be decoded."
}

API Key IP Restricted¶

HTTP 403 with ErrorType set to OE_API_KEY_IP_RESTRICTED means another API key has already claimed this request's public IP address. Stop sending inspections with the rejected key and follow the recovery guidance in Error Handling. Do not retry automatically or switch to the fallback URL for this error.

Free Usage Limit Reached¶

HTTP 429 with ErrorType set to OE_FREE_USAGE_LIMIT_REACHED means the monthly free allowance has been exhausted and either billing is not set up or Free Usage Only is enabled.

Stop sending inspections until the allowance resets, or until the account owner sets up billing and turns off Free Usage Only at OctoEverywhere.com/gadgetapi. Creating a new context or switching to the fallback URL does not reset the allowance.

Handle this error separately from temporary rate limiting. Do not retry it in a loop; a Retry-After header does not mean the monthly allowance has reset.

Calling Pattern¶

After each successful request, wait for your inspection interval, then send the next snapshot. See retries and fallback URLs and error handling for recovery steps.