For Builders

Introduction

The DIVS Python SDK enables developers to integrate trustless image claim verification directly into their applications, bots, browser extensions, or moderation tools. This guide helps you make your first verification request in under 5 minutes, giving you access to decentralized image analysis powered by independent Vision-Language Model (VLM) nodes.

---

1️⃣ Prerequisites

Before you start, you’ll need:

• ✅ An account on Witness Chain: Sign up here

• ✅ An API key : Generate from this dashboard

Copy the generated key (prefixed wtns_)

• ✅ A Python 3.10.17+ environment

python -m venv witnesschain_env
source witnesschain_env/bin/activate
python --version 
python3 --version 
pip --version

• ✅ A publicly accessible image URL or base64-encoded image

---

2️⃣ Install the SDK

Install the official Witness SDK via PyPI

pip install witnesschain

Verify installation:

python -c "import witnesschain; print('witnesschain imported successfully')"

---

---

3️⃣ Verify Your Image

Option 1 – Public Image URL

import asyncio
from infinitywatch import Infinitywatch

API_KEY = "YOUR_WITNESSCHAIN_DIVS_KEY_HERE"

async def main():
    client = Infinitywatch(api_key=API_KEY)

    async for node_response in client.query(
        "what does this image suggest?",
        models=["Qwen/Qwen2.5-VL-7B-Instruct"],
        inputs=["https://img.freepik.com/premium-psd/peanut-butter-png-transparent_955012-13366.jpg?w=360"],  # Publicly accessible URL
    ):
        print(node_response.model_response)

if __name__ == "__main__":
    asyncio.run(main())

---

Option 2 – Local File Path (from your script's directory) ✅

import asyncio
from infinitywatch import Infinitywatch

API_KEY = "YOUR_WITNESSCHAIN_DIVS_KEY_HERE"

async def main():
    client = Infinitywatch(api_key=API_KEY)

    async for node_response in client.query(
        "what does this image suggest?",
        models=["Qwen/Qwen2.5-VL-7B-Instruct"],
        inputs=["./peanut-butter.png"],  # Local file in the same directory
    ):
        print(node_response.model_response)

if __name__ == "__main__":
    asyncio.run(main())

---

Option 3 – Base64-Encoded Image

import asyncio
import base64
from infinitywatch import Infinitywatch

API_KEY = "YOUR_WITNESSCHAIN_DIVS_KEY_HERE"

async def main():
    client = Infinitywatch(api_key=API_KEY)

    # Convert image to base64
    with open("./peanut-butter.png", "rb") as f:
        img_base64 = base64.b64encode(f.read()).decode("utf-8")

    async for node_response in client.query(
        "what does this image suggest?",
        models=["Qwen/Qwen2.5-VL-7B-Instruct"],
        inputs=[img_base64],  # Base64 string instead of file path
    ):
        print(node_response.model_response)

if __name__ == "__main__":
    asyncio.run(main())

---

✅ Key Points:

• You can pass URLs, local file paths, or base64 strings interchangeably in inputs=[...].

• Local files are easiest for dev environments; URLs are useful for remote images; base64 works well for in-memory or private images.

---

4️⃣ Sample Output

InfinitywatchNodeResponse (
   node_id='IPv4/0x0b54e605b867eba82602fee2dfcb76204177fe0a', 
   model_response='The image suggests a spoonful of peanut butter, which is often associated with    snacks or meals that include this popular spread.', 
   model='Qwen/Qwen2.5-VL-7B-Instruct', 
   challenge_id='394f4756-c390-4587-be7b-1e35c736b056'
)

---

5️⃣ Advanced Usage

Verify Multiple Images

async for resp in client.query(
    "Describe what’s happening in these frames.",
    models=["HuggingFaceTB/SmolVLM2-2.2B-Instruct"],
    inputs=["./frame1.jpeg", "./frame2.jpeg", "./frame3.jpeg"],
):
    ...

---

Custom options

async for resp in client.query(
    "Summarize this diagram.",
    models=["THUDM/GLM-4.1V-9B-Thinking"],
    inputs=["https://example.com/image.png"],
    model_parameters = {
        max_tokens=512,              
        temperature=0.3,
    }             
):
    ...

---

6️⃣ Best Practices

• Cache Results: Avoid repeated verifications for the same image+claim pair.

---

7️⃣ Example Use Cases

• Fact-checking bots: Validate viral images before sharing.

• News authenticity tools: Detect manipulated or miscaptioned images.

• Moderation pipelines: Flag potentially misleading visuals.

• Browser extensions: Give end-users quick access to decentralized verification results.

---

8️⃣ Troubleshooting

• ModuleNotFoundError: No module named 'witnesschain' Ensure you ran pip install witnesschain in the same environment.

• Authentication errors

  • Check that WITNESSCHAIN_API_KEY matches exactly the string on your dashboard.

  • Confirm you haven’t accidentally revoked the key or has been expired.

• Slow or no responses

  • Verify your network connectivity.

  • Check the challenge_id for more insights

---