Quick Start
Install the JavaScript or Python SDK, set your provider key in the process environment and use your publisher ID. You can install and configure directly or use the optional assistant; SDK usage does not require CLI login. The examples below use the included local processing runtime.
Integrating with a coding agent? Start with the agent guide.
The JavaScript SDK ships the public docs as Markdown. Open the index for the installed version at
node_modules/notpixel/dist/docs/index.md.
JavaScript / TypeScript
import Ads from 'notpixel';
const ads = new Ads({
publisherId: 'YOUR_PUBLISHER_ID',
model: 'openai/YOUR_MODEL',
});
const result = await ads.offer({ input: 'How can I optimize PostgreSQL?' });
console.log(result.text);Python
from notpixel import Ads, AsyncAds
ads = Ads(publisher_id="YOUR_PUBLISHER_ID", model="openai/YOUR_MODEL")
result = ads.offer(input="How can I optimize PostgreSQL?")
print(result.text)
# Inside an async function:
async_ads = AsyncAds(publisher_id="YOUR_PUBLISHER_ID", model="openai/YOUR_MODEL")
result = await async_ads.offer(input="How can I optimize PostgreSQL?")Both SDKs run local ad matching and LLM inference concurrently, then append an identified sponsored block if an ad is available. The NotPixel ad API receives an embedding vector; the selected LLM provider receives your original prompt.
Keep your existing LLM client
const result = await ads.respond({
input: prompt,
llm: async () => ({ text: await callYourLLM(prompt) }),
});result = await async_ads.respond(
input=prompt,
llm=lambda: call_your_llm(prompt),
)Fetch only an ad
getAd() / get_ad() require a publisher ID and input, without a model or LLM key.
const ads = new Ads({ publisherId: 'YOUR_PUBLISHER_ID' });
const ad = await ads.getAd({ input: 'Database optimization tools' });
if (ad) console.log(ad.headline, ad.cta.url);ads = Ads(publisher_id="YOUR_PUBLISHER_ID")
ad = ads.get_ad(input="Database optimization tools")
if ad:
print(ad.headline, ad.cta.url)Local processing is included by default with npm install notpixel or
pip install notpixel. For explicit remote processing, import from
notpixel/remote (Python: from notpixel.remote import Ads, AsyncAds).
The optional assistant can configure either mode for you. If model loading fails
or no ad matches, continue your normal application response. Preserve ad tracking metadata when
passing results from the backend to your interface.