x402 NFT image search API

This API searches the images of every Algorand NFT in Nodely’s IPFS cache by meaning, not by file name. You can search with a text query in any language, with an image of your own, or with the CID of an image already in the cache. Every image is embedded with the Qwen3-VL-Embedding-2B model, and the API answers with the nearest images, their IPFS CIDs, similarity scores and the Algorand assets (ASA ids) that reference them.

It costs 0.005 USDC per call, paid with x402 in USDC on Algorand. This API doesn’t take payment on Base or Arc.

Endpoint	What it searches with
`GET https://x402.api.nodely.io/v1/images/search?q=...`	A text query, 1–1000 characters, any language
`POST https://x402.api.nodely.io/v1/images/search`	An image: png, jpeg, gif, webp or bmp up to 16 MiB
`GET https://x402.api.nodely.io/v1/images/similar/{cid}`	An image already in the cache, by its IPFS CID (“more like this”)

Parameters

All three endpoints take the same query parameters:

Parameter	Notes
`k`	Number of results, 1–100, default 20
`assets`	`0` leaves out the referencing Algorand assets, which is faster

GET /v1/images/search also takes q (required). POST /v1/images/search takes the image either as a raw body with an image/* Content-Type, or as JSON {"image": "<base64 or data URL>"}. /v1/images/similar/{cid} leaves out the queried image’s own content from the results.

Response

{
  "results": [
    {
      "cid": "bafkrei…",
      "mime": "image/png",
      "score": 0.61,
      "assets": [
        { "asset": 1234567890, "key": "url", "depth": 0 }
      ]
    }
  ]
}

Field	Meaning
`cid`	IPFS CID of the image. Fetch it through any IPFS gateway
`mime`	Image type
`score`	Cosine similarity: higher is closer
`assets`	Up to 5 Algorand assets that reference the CID. `key` says where (the asset URL, ARC-19, ARC-69 media…); `depth` is `0` for the asset’s own URL and `1` for a reference inside its metadata

What is not charged

An invalid request (400).
An upload that isn’t a supported image (415).
A similar call with a CID that isn’t an embedded image in the cache (404).
A search where the embedding model or the index doesn’t answer (503).

Example

Using the Algorand paid fetch client from Pricing & payment:

// Text search
const res = await paidFetch("https://x402.api.nodely.io/v1/images/search?q=pixel%20art%20frog&k=10");
console.log(await res.json());

// Reverse image search with a local file
import { readFile } from "node:fs/promises";
const img = await paidFetch("https://x402.api.nodely.io/v1/images/search?k=10", {
  method: "POST",
  headers: { "Content-Type": "image/png" },
  body: await readFile("frog.png"),
});
console.log(await img.json());

Free routes in this namespace: