Node.js SDK

The Node.js SDK is the recommended integration path for Node.js and TypeScript applications. It handles authentication, uploads, polling, result parsing, and streaming.

Installation

npm install @ice9/sdk

Authentication

Pass your API key directly or use ICE9_API_KEY:

export ICE9_API_KEY=ice9_...

import { Ice9 } from "@ice9/sdk";

const client = new Ice9({ apiKey: process.env.ICE9_API_KEY });

Quickstart

import { Ice9 } from "@ice9/sdk";

const client = new Ice9({ apiKey: process.env.ICE9_API_KEY });
const image = await client.analyze("photo.jpg");

console.log(image.isNsfw);
console.log(image.category);
console.log(image.scene?.type);
console.log(image.moderation.reason);

Input types

analyze() accepts:

local file paths
image URLs
Buffer
Uint8Array

const resultA = await client.analyze("photo.jpg");
const resultB = await client.analyze("https://example.com/photo.jpg");
const resultC = await client.analyze(buffer);

Tiers and service discovery

If you omit tier, the SDK uses the baseline tier, currently free.

const image = await client.analyze("photo.jpg");
const upgraded = await client.analyze("photo.jpg", { tier: "basic" });

const tiers = await client.tiers();
const services = await client.services();

See API Reference for the raw tier definitions.

Result model

The SDK exposes image-level helpers first and keeps raw service outputs available under image.services.

Core helpers

image.isNsfw
image.isSafe
image.category
image.caption
image.scene
image.moderation
image.nouns
image.verbs
image.services

Scene summary

image.scene is derived from content_analysis and provides a product-shaped summary:

image.scene?.type
image.scene?.intimacy
image.scene?.activity
image.scene?.activities
image.scene?.anatomyExposed
image.scene?.people
image.scene?.gender

Moderation helpers

const image = await client.analyze("photo.jpg");

if (image.isNsfw) {
  console.log(image.moderation.reason);
  await image.moderation.censor("photo.jpg", { output: "photo-censored.jpg" });
}

Raw service access

Use image.services when you need service-level payloads:

console.log(image.services.nudenet);
console.log(image.services.colors);
console.log(image.services.metadata);

Streaming

Use stream: true to receive partial AnalysisResult objects as services complete:

import { Ice9 } from "@ice9/sdk";

const client = new Ice9({ apiKey: process.env.ICE9_API_KEY });

for await (const partial of client.analyze("photo.jpg", { tier: "basic", stream: true })) {
  if (partial.isComplete) {
    console.log("final caption:", partial.caption);
  } else {
    console.log("services seen:", partial.servicesSubmitted);
  }
}

Retrieving results later

Use the retrieval helpers if you already have an imageId:

const status = await client.getStatus(1234);
const result = await client.getResult(1234);

getStatus() returns the raw /status payload. getResult() returns a parsed AnalysisResult.

Serialization

Use toJSON() or toJson() to serialize results:

const payload = image.toJSON();
const pretty = image.toJson(2);

Examples

Basic analysis

import { Ice9 } from "@ice9/sdk";

const client = new Ice9({ apiKey: process.env.ICE9_API_KEY });
const image = await client.analyze("photo.jpg", { tier: "basic" });

console.log(image.caption);
console.log(image.category);
console.log(image.scene?.type, image.scene?.intimacy);

for (const noun of image.nouns?.validated ?? []) {
  console.log(noun);
}

Streaming

import { Ice9 } from "@ice9/sdk";

const client = new Ice9({ apiKey: process.env.ICE9_API_KEY });

for await (const partial of client.analyze("photo.jpg", { tier: "basic", stream: true })) {
  console.log(partial.isComplete ? partial.caption : partial.servicesSubmitted);
}

Full runnable examples

For complete scripts and local downloads:

https://github.com/ice9innovations/ice9-sdk/tree/main/nodejs/examples