Spaces:

sh4lu-z
/

cipher-md-api

Running

App Files Files Community

cipher-md-api / README.md

sh4lu-z

docs: update API documentation and initialize new service modules

493b302 3 days ago

preview code

Raw

History Blame Contribute Delete

21.9 kB

metadata

title: Cipher MD API Bundle
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860

🚀 Cipher-MD API Bundle

All requests go through the Gateway on port 7860.
Base URL: https://your-space.hf.space

Gateway prefix routing:

Prefix	Service	Internal Port
`/visuals/...`	Visuals Engine (Node.js)	7861
`/audio_server/...`	Audio Engine (FastAPI)	7862
`/cipher_sticker/...`	Sticker Engine (Flask)	7863
`/scanner/...`	Scanner Engine (FastAPI)	7864

📋 Table of Contents

Gateway
Visuals Engine
Audio Engine
Sticker Engine
Scanner Engine
- GET /scanner
- POST /scanner/scan

🔀 Gateway

`GET /`

Server status + RAM info

import requests

res = requests.get("https://your-space.hf.space/")
print(res.json())

Response:

{
  "message": "🚀 Cipher-MD Smart API Gateway is Running!",
  "status": "Active",
  "ram_monitoring": true,
  "free_ram_mb": 2048,
  "queued_requests": 0
}

🎨 1. Visuals Engine

`GET /visuals/`

Server check.

import requests
res = requests.get("https://your-space.hf.space/visuals/")
print(res.text)  # "🚀 Cipher-MD ULTRA-SHARP ENGINE"

`POST /visuals/welcome`

Welcome image generate කරනවා (profile pic + group name + member count + optional username).

Form-data Parameters:

Parameter	Type	Required	Description
`image`	file	✅	Profile picture (PNG/JPG)
`title`	string	✅	Group name
`count`	string	✅	Member number
`userName`	string	❌	New member's name (shown separately in cyan)

Note: Sinhala text in title or userName is automatically translated to English via Google Translate.

import requests

with open("profile.jpg", "rb") as img:
    res = requests.post(
        "https://your-space.hf.space/visuals/welcome",
        files={"image": img},
        data={
            "title": "Cipher Squad",
            "count": "42",
            "userName": "Kamal"        # Optional — omit if not needed
        }
    )

with open("welcome.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (1024×1024 px welcome card)

`POST /visuals/watermark`

Image-ek-ta watermark danna.

Form-data Parameters:

Parameter	Type	Required	Description
`image`	file	✅	Any PNG/JPG image
`watermarkText`	string	❌	Custom watermark text (default: `CIPHER-MD GEN ENGINE`)

import requests

with open("photo.png", "rb") as img:
    res = requests.post(
        "https://your-space.hf.space/visuals/watermark",
        files={"image": img},
        data={"watermarkText": "© My Bot 2025"}   # Optional
    )

with open("watermarked.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (same dimensions as input)

`POST /visuals/chart/candle`

Candlestick chart generate කරනවා.

JSON Body Parameters:

Parameter	Type	Required	Description
`symbol`	string	✅	Trading pair (e.g. `BTC`)
`change`	string	✅	24h % change (e.g. `"+2.5"`)
`currentPrice`	string	✅	Current price
`candles`	array	✅	Array of OHLCV candle objects

Candle object:

{ "open": 65000, "high": 66000, "low": 64500, "close": 65800, "volume": 1200 }

import requests

payload = {
    "symbol": "BTC",
    "change": "+2.5",
    "currentPrice": "65800",
    "candles": [
        {"open": 64000, "high": 65500, "low": 63800, "close": 65200, "volume": 980},
        {"open": 65200, "high": 66100, "low": 64900, "close": 65800, "volume": 1200},
        {"open": 65800, "high": 67000, "low": 65500, "close": 66500, "volume": 1500},
    ]
}

res = requests.post(
    "https://your-space.hf.space/visuals/chart/candle",
    json=payload
)

with open("candle_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K chart — 2400×1500 px)

`POST /visuals/chart/p2p`

USDT/LKR P2P rate line chart.

JSON Body Parameters:

Parameter	Type	Required	Description
`currentRate`	number	✅	Current rate
`history`	array	✅	Array of `{rate: number}` objects

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/p2p",
    json={
        "currentRate": 325.5,
        "history": [
            {"rate": 310}, {"rate": 315}, {"rate": 318},
            {"rate": 320}, {"rate": 325}, {"rate": 325.5}
        ]
    }
)
with open("p2p_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K line chart)

`POST /visuals/chart/forex`

USD/LKR official rate chart.

JSON Body Parameters:

Parameter	Type	Required	Description
`currentRate`	number	✅	Current rate
`history`	array	✅	Array of `{rate: number}` objects

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/forex",
    json={
        "currentRate": 298.5,
        "history": [{"rate": 290}, {"rate": 293}, {"rate": 295}, {"rate": 298.5}]
    }
)
with open("forex_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K line chart, green theme)

`POST /visuals/chart/gold`

Gold (24K) price chart.

JSON Body Parameters:

Parameter	Type	Required	Description
`currentRate`	number	✅	Current gold price
`history`	array	✅	Array of `{value: number}` or `{price: number}` objects

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/gold",
    json={
        "currentRate": 580000,
        "history": [
            {"value": 570000}, {"value": 575000}, {"value": 580000}
        ]
    }
)
with open("gold_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K line chart, gold theme)

`POST /visuals/chart/cse`

CSE ASPI Index chart.

JSON Body Parameters:

Parameter	Type	Required	Description
`currentRate`	number	✅	Current ASPI value
`history`	array	✅	Array of `{value: number}` objects

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/cse",
    json={
        "currentRate": 12500,
        "history": [{"value": 12000}, {"value": 12200}, {"value": 12500}]
    }
)
with open("cse_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K line chart, purple theme)

`POST /visuals/chart/fear`

Fear & Greed Index chart.

JSON Body Parameters:

Parameter	Type	Required	Description
`history`	array	✅	Array of `{value: number}` (0–100)

Color is auto-selected: green if last value > 50, red if ≤ 50.

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/fear",
    json={
        "history": [
            {"value": 30}, {"value": 45}, {"value": 60},
            {"value": 55}, {"value": 72}
        ]
    }
)
with open("fear_chart.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (4K line chart)

`POST /visuals/chart/nft`

NFT collection info card.

JSON Body Parameters (inside data key):

Parameter	Type	Required	Description
`data.name`	string	✅	Collection name
`data.chain`	string	✅	Blockchain (e.g. `ethereum`)
`data.floor_price`	number	✅	Floor price
`data.floor_price_symbol`	string	✅	Symbol (e.g. `ETH`)
`data.total_volume`	number	✅	Total trade volume
`data.owner_count`	number	✅	Owner count
`data.image_url`	string	❌	Collection image URL

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/nft",
    json={
        "data": {
            "name": "Bored Ape Yacht Club",
            "chain": "ethereum",
            "floor_price": 12.5,
            "floor_price_symbol": "ETH",
            "total_volume": 850000,
            "owner_count": 6400,
            "image_url": "https://example.com/nft.png"
        }
    }
)
with open("nft_card.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (800×400 px card)

`POST /visuals/chart/arb`

Crypto arbitrage monitor card.

JSON Body Parameters:

Parameter	Type	Required	Description
`coin`	string	✅	Coin name (e.g. `BTC`)
`exData`	array	✅	Array of exchange objects

Exchange object:

{ "name": "Binance", "price": 65800 }

import requests

res = requests.post(
    "https://your-space.hf.space/visuals/chart/arb",
    json={
        "coin": "BTC",
        "exData": [
            {"name": "Binance", "price": 65800},
            {"name": "Bybit",   "price": 65750},
            {"name": "Kraken",  "price": 65900},
            {"name": "OKX",     "price": 65820}
        ]
    }
)
with open("arb_card.png", "wb") as f:
    f.write(res.content)

Response: image/png binary (900×600 px arbitrage card)

🎛️ 2. Audio Engine

`GET /audio_server/`

Server status check.

import requests
res = requests.get("https://your-space.hf.space/audio_server/")
print(res.json())

Response:

{
  "service": "Cipher-MD Audio Engine",
  "version": "3.0",
  "endpoints": ["/process", "/info", "/effects", "/trim"]
}

`GET /audio_server/effects`

Available effects list.

import requests
res = requests.get("https://your-space.hf.space/audio_server/effects")
print(res.json())

Response:

{
  "effects": {
    "bass":      ["bass_studio", "bass_edm", "bass_car", "bass_slap", "bass_heavy", "8d_bass"],
    "spatial":   ["8d_audio", "3d_surround", "wide_stereo", "hall_reverb", "stadium"],
    "vocal":     ["vocal_boost", "crystal_clear", "presence"],
    "creative":  ["nightcore", "daycore", "slow_reverb", "vaporwave", "lofi_chill",
                  "reverse", "underwater", "robot", "chipmunk", "telephone"],
    "mastering": ["compressor", "limiter", "loudness", "concert", "clean_master"]
  },
  "level_range": "1-20 (bass effects only)",
  "formats": ["mp3", "ogg", "wav"]
}

`POST /audio_server/info`

Audio file metadata ගන්නවා.

Form-data Parameters:

Parameter	Type	Required	Description
`file`	file	✅	MP3/WAV/OGG/MP4/any audio

import requests

with open("song.mp3", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/audio_server/info",
        files={"file": f}
    )

print(res.json())

Response:

{
  "duration": 214.5,
  "size_bytes": 8621056,
  "bit_rate": 320000,
  "format": "mp3",
  "codec": "mp3",
  "sample_rate": "44100",
  "channels": 2,
  "title": "Shape of You",
  "artist": "Ed Sheeran"
}

`POST /audio_server/process`

Audio effect apply කරනවා.

Form-data Parameters:

Parameter	Type	Required	Default	Description
`file`	file	✅	—	MP3/WAV/OGG audio file
`effect`	string	❌	`bass_studio`	Effect name (see `/effects`)
`level`	int	❌	`10`	Bass strength 1–20 (bass effects only)
`output_format`	string	❌	`mp3`	Output format: `mp3` / `ogg` / `wav`
`use_dj_mix`	bool	❌	`false`	Mix with `assets/intro.mp3` + `assets/outro.mp3`

Effect Categories:

Effect	Description
`bass_studio`	Studio-quality bass boost
`bass_edm`	EDM-style heavy bass
`bass_car`	Deep sub-bass (car system)
`bass_slap`	Punchy mid-bass slap
`bass_heavy`	Maximum sub-bass
`8d_audio`	8D panning effect
`8d_bass`	8D + bass combo
`3d_surround`	3D surround simulation
`wide_stereo`	Wide stereo widening
`hall_reverb`	Concert hall reverb
`stadium`	Stadium echo effect
`vocal_boost`	Enhance vocals
`crystal_clear`	Clarity boost
`presence`	Mid presence boost
`nightcore`	Fast + high pitch
`daycore`	Slow + reverb
`slow_reverb`	Slowed + reverb
`vaporwave`	Vaporwave aesthetic
`lofi_chill`	Lo-fi style
`reverse`	Reverse audio
`underwater`	Underwater effect
`robot`	Robot voice
`chipmunk`	Chipmunk high pitch
`telephone`	Phone call effect
`compressor`	Dynamic compression
`limiter`	Peak limiter
`loudness`	Broadcast loudness
`concert`	Concert ambience
`clean_master`	Professional master

import requests

# Simple bass boost
with open("song.mp3", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/audio_server/process",
        files={"file": ("song.mp3", f, "audio/mpeg")},
        data={
            "effect": "bass_car",
            "level": "15",
            "output_format": "mp3"
        }
    )

with open("output.mp3", "wb") as out:
    out.write(res.content)

# With DJ intro/outro mix (requires assets/intro.mp3 + assets/outro.mp3)
with open("song.mp3", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/audio_server/process",
        files={"file": ("song.mp3", f, "audio/mpeg")},
        data={
            "effect": "bass_studio",
            "level": "12",
            "output_format": "mp3",
            "use_dj_mix": "true"
        }
    )

with open("dj_output.mp3", "wb") as out:
    out.write(res.content)

Response: audio/mpeg (or audio/ogg / audio/wav) binary
Filename header: Cipher_<effect>.mp3

Error Responses:

{ "detail": "output_format must be mp3, ogg, or wav" }
{ "detail": "DJ Mix requires intro.mp3 and outro.mp3 in the assets folder. Set use_dj_mix=false to process without them." }
{ "detail": "FFmpeg processing failed: ..." }

`POST /audio_server/trim`

Audio cut/trim + optional effect.

Form-data Parameters:

Parameter	Type	Required	Default	Description
`file`	file	✅	—	Audio file
`start`	float	❌	`0.0`	Start time in seconds
`end`	float	❌	`-1`	End time in seconds (-1 = until end)
`output_format`	string	❌	`mp3`	`mp3` / `ogg` / `wav`
`effect`	string	❌	`""`	Optional effect to apply after trim
`level`	int	❌	`10`	Bass level if effect is bass-type

import requests

# Trim 30s to 90s + apply nightcore
with open("song.mp3", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/audio_server/trim",
        files={"file": ("song.mp3", f, "audio/mpeg")},
        data={
            "start": "30",
            "end": "90",
            "output_format": "mp3",
            "effect": "nightcore"
        }
    )

with open("trimmed.mp3", "wb") as out:
    out.write(res.content)

# Trim only (no effect) — 0s to 60s
with open("song.mp3", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/audio_server/trim",
        files={"file": ("song.mp3", f, "audio/mpeg")},
        data={"start": "0", "end": "60"}
    )

with open("clip.mp3", "wb") as out:
    out.write(res.content)

Response: audio/mpeg binary, filename: Cipher_trimmed.mp3

🎭 3. Sticker Engine

`GET /cipher_sticker/`

Server check.

import requests
res = requests.get("https://your-space.hf.space/cipher_sticker/")
print(res.text)  # "🔥 Cipher_MD Smart Engine (Guaranteed < 1MB) Running!"

`POST /cipher_sticker/sticker`

Single animated/static WhatsApp sticker generate කරනවා.

Form-data Parameters:

Parameter	Type	Required	Description
`file`	file	✅	Video (MP4/GIF/MOV/AVI/MKV/WEBM) or image (PNG/JPG)
Any extra form field	string	❌	Added as WebP metadata (e.g. `packname`, `author`)

Auto-compresses to stay under 1MB (WhatsApp limit).
Smart resize attempts: 512px → 384px → 320px → 256px.

import requests

# Animated sticker from video
with open("clip.mp4", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/cipher_sticker/sticker",
        files={"file": ("clip.mp4", f, "video/mp4")},
        data={
            "packname": "Cipher Stickers",   # Optional metadata
            "author": "Cipher MD Bot"         # Optional metadata
        }
    )

with open("sticker.webp", "wb") as out:
    out.write(res.content)

# Static sticker from image
with open("photo.png", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/cipher_sticker/sticker",
        files={"file": ("photo.png", f, "image/png")},
        data={"author": "My Bot"}
    )

with open("static_sticker.webp", "wb") as out:
    out.write(res.content)

Response: image/webp binary (animated or static WebP, <1MB)

Error Responses:

{ "error": "No file uploaded" }
{ "error": "Failed to generate valid sticker" }

`POST /cipher_sticker/pack`

Long video → multiple stickers pack (ZIP file).

Form-data Parameters:

Parameter	Type	Required	Description
`file`	file	✅	Video file (max 2 minutes / 130 seconds)
Any extra form field	string	❌	Metadata for ALL stickers in pack (e.g. `packname`, `author`)

Video is split into 10-second segments, each compressed to <1MB.
Returns a ZIP containing numbered WebP files (1.webp, 2.webp, ...).

import requests

# Generate sticker pack from 1-minute video
with open("video.mp4", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/cipher_sticker/pack",
        files={"file": ("video.mp4", f, "video/mp4")},
        data={
            "packname": "Cipher Animated Pack",
            "author": "Cipher MD"
        }
    )

with open("sticker_pack.zip", "wb") as out:
    out.write(res.content)

# Extract the ZIP
import zipfile, io
with zipfile.ZipFile(io.BytesIO(res.content)) as z:
    z.extractall("sticker_pack/")
    print("Stickers:", z.namelist())  # ['1.webp', '2.webp', '3.webp', ...]

Response: application/zip binary
Filename header: <uuid>.zip

Error Responses:

{ "error": "No file uploaded" }
{ "error": "Video too long (Max 2 mins)" }

🔍 4. Scanner Engine

`GET /scanner/`

Server check.

import requests
res = requests.get("https://your-space.hf.space/scanner/")
print(res.json())

Response:

{ "message": "Cipher-MD Scanner Engine is Running! 🚀" }

`POST /scanner/scan`

Image watermark reveal/remove කරනවා.

Form-data Parameters:

Parameter	Type	Required	Description
`image`	file	✅	PNG/JPG image to scan

import requests

with open("suspicious_image.png", "rb") as f:
    res = requests.post(
        "https://your-space.hf.space/scanner/scan",
        files={"image": ("suspicious_image.png", f, "image/png")}
    )

if res.status_code == 200:
    with open("revealed.png", "wb") as out:
        out.write(res.content)
else:
    print(res.json())  # {"error": "..."}

Response: image/png binary (revealed watermark image)

Error Responses:

{ "error": "Processing failed" }
{ "error": "<exception message>" }

📦 Dependencies

Node.js (Visuals + Gateway)

express, skia-canvas, multer, axios,
wa-sticker-formatter, http-proxy-middleware

Python (Audio + Sticker + Scanner)

fastapi, uvicorn, python-multipart, aiofiles,
flask, ffmpeg (system), ffprobe (system)

⚡ Notes

All heavy operations (audio processing, sticker generation) run with auto temp file cleanup.
The Gateway has RAM monitoring — requests are queued when free RAM < 500MB.
Gateway timeout: 5 minutes per request.
Audio level parameter only affects bass-type effects (bass_*, 8d_bass). For other effects it is ignored.
Sticker engine guarantees output < 1MB by progressively reducing quality and size.