hyc-image-mcp Tutorial: Image Understanding & OCR with MCP + NexaAPI (Python Guide 2026)

Install hyc-image-mcp

pip install hyc-image-mcp

pip install nexaapi hyc-image-mcp requests Pillow

image_ocr_pipeline.py

# Image Generation + OCR Pipeline
# NexaAPI ($0.003/image) + hyc-image-mcp
# Get free API key: https://rapidapi.com/user/nexaquency

import requests
import os
from nexaapi import NexaAPI

# ─── Step 1: Initialize NexaAPI ───────────────────────────────────────────────
client = NexaAPI(api_key=os.environ.get('NEXAAPI_KEY', 'YOUR_RAPIDAPI_KEY'))

# ─── Step 2: Generate an image with NexaAPI ───────────────────────────────────
print("🎨 Generating image with NexaAPI...")
response = client.image.generate(
    model='flux-schnell',          # Fast, high-quality, $0.003/image
    prompt='A business invoice document with itemized costs and totals, '
           'clean white background, professional typography',
    width=1024,
    height=1024
)

image_url = response.image_url
print(f"✅ Image generated: {image_url}")
print(f"   Cost: $0.003")

# ─── Step 3: Download the image ───────────────────────────────────────────────
print("\n📥 Downloading image...")
img_data = requests.get(image_url, timeout=30).content
with open('generated_invoice.png', 'wb') as f:
    f.write(img_data)
print("✅ Saved as generated_invoice.png")

# ─── Step 4: Use hyc-image-mcp for OCR/image understanding ───────────────────
# hyc-image-mcp exposes an MCP server — integrate it into your agent pipeline:
# Option A: Run as MCP server (for Claude Desktop / agent frameworks)
#   uvx hyc-image-mcp
#   or: python -m hyc_image_mcp
#
# Option B: Use the underlying vision capability directly
# The package provides image understanding tools compatible with MCP protocol.
# Your MCP-enabled agent (Claude, GPT-4, etc.) can then call:
#   - analyze_image(path="generated_invoice.png")
#   - extract_text(path="generated_invoice.png")
#   - describe_image(path="generated_invoice.png")

print("\n🔍 Image ready for hyc-image-mcp OCR processing")
print("   Configure in your MCP client:")
print('   {"mcpServers": {"hyc-image-mcp": {"command": "uvx", "args": ["hyc-image-mcp"]}}}')
print("\n📊 Pipeline Summary:")
print("   Image generated: generated_invoice.png")
print("   Generation cost: $0.003 (NexaAPI)")
print("   OCR: hyc-image-mcp MCP server")
print("   Total pipeline cost for 1,000 images: $3.00")
print("\n🔗 Resources:")
print("   NexaAPI: https://nexa-api.com")
print("   Free tier: https://rapidapi.com/user/nexaquency")
print("   PyPI NexaAPI: https://pypi.org/project/nexaapi/")
print("   PyPI hyc-image-mcp: https://pypi.org/project/hyc-image-mcp/")

# Available NexaAPI image models (all at $0.003/image):
models = [
    'flux-schnell',    # Fastest, great for prototyping
    'flux-dev',        # Higher quality, more detail
    'sdxl',            # Stable Diffusion XL
    'sd3',             # Stable Diffusion 3
    'playground-v2',   # Aesthetic, vibrant outputs
]

# Generate with any model:
for model in models[:2]:
    result = client.image.generate(
        model=model,
        prompt='A product label with text, barcode, and pricing information',
        width=1024, height=1024
    )
    print(f"{model}: {result.image_url}")

Install

npm install nexaapi node-fetch

image_ocr_pipeline.js

// Image Generation + OCR Pipeline (JavaScript)
// NexaAPI + hyc-image-mcp
// npm install nexaapi
// Get free API key: https://rapidapi.com/user/nexaquency

import NexaAPI from 'nexaapi';
import fs from 'fs';
import https from 'https';
import path from 'path';

const client = new NexaAPI({
  apiKey: process.env.NEXAAPI_KEY || 'YOUR_RAPIDAPI_KEY'
});

async function imageOCRPipeline() {
  console.log('🎨 Generating image with NexaAPI...');

  // Step 1: Generate image
  const response = await client.image.generate({
    model: 'flux-schnell',
    prompt: 'A business invoice document with itemized costs and totals, '
          + 'clean white background, professional typography',
    width: 1024,
    height: 1024
  });

  const imageUrl = response.imageUrl;
  console.log(`✅ Image generated: ${imageUrl}`);
  console.log('   Cost: $0.003');

  // Step 2: Download the image
  console.log('\n📥 Downloading image...');
  await downloadImage(imageUrl, 'generated_invoice.png');
  console.log('✅ Saved as generated_invoice.png');

  // Step 3: Configure hyc-image-mcp for your MCP client
  const mcpConfig = {
    mcpServers: {
      'hyc-image-mcp': {
        command: 'uvx',
        args: ['hyc-image-mcp']
      }
    }
  };

  console.log('\n🔍 MCP server config for hyc-image-mcp:');
  console.log(JSON.stringify(mcpConfig, null, 2));

  console.log('\n📊 Pipeline complete!');
  console.log('   NexaAPI docs: https://nexa-api.com');
  console.log('   Free tier: https://rapidapi.com/user/nexaquency');
  console.log('   npm: https://www.npmjs.com/package/nexaapi');
}

function downloadImage(url, filename) {
  return new Promise((resolve, reject) => {
    const file = fs.createWriteStream(filename);
    https.get(url, (response) => {
      response.pipe(file);
      file.on('finish', () => { file.close(); resolve(); });
    }).on('error', reject);
  });
}

imageOCRPipeline().catch(console.error);

{
  "mcpServers": {
    "hyc-image-mcp": {
      "command": "uvx",
      "args": ["hyc-image-mcp"]
    }
  }
}

# Install
pip install hyc-image-mcp

# Run as MCP server
python -m hyc_image_mcp

# Or with uv
uvx hyc-image-mcp