ListifyAI

API-only service: product photo in → Gemini vision + LangGraph orchestration → SEO copy, creative briefs, and multi-agent verification. See CONVENTION.md for request/response shapes your UI should use.

Setup

cd ListifyAI
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# Edit .env and set GEMINI_API_KEY

Run

uvicorn listifyai.api.main:app --reload --host 0.0.0.0 --port 8000

• OpenAPI UI: http://localhost:8000/docs
• OpenAPI JSON: http://localhost:8000/openapi.json

curl examples

Health:

curl -s http://localhost:8000/health | jq

Generate listing (multipart + JSON payload string):

curl -s -X POST http://localhost:8000/v1/listings/generate \
  -F "image=@examples/sample.jpg;type=image/jpeg" \
  -F 'payload={"locale":"en","marketplaces":["amazon","generic"],"user_hints":{"brand":"Demo"}}' \
  | jq

With verification repair (text QA loop + per-shot image regen on minor issues):

curl -s -X POST http://localhost:8000/v1/listings/generate \
  -F "image=@examples/sample.jpg;type=image/jpeg" \
  -F 'payload={"verification_repair":true,"image_output":{"aspect_ratio":"1:1"}}' \
  | jq

With optional generated-image hints (when ENABLE_IMAGE_GENERATION=1):

curl -s -X POST http://localhost:8000/v1/listings/generate \
  -F "image=@examples/sample.jpg;type=image/jpeg" \
  -F 'payload={"image_output":{"aspect_ratio":"1:1","image_size":"2K","max_side":2000,"output_mime_type":"image/jpeg"}}' \
  | jq

Replace examples/sample.jpg with any JPEG/PNG/WebP under MAX_UPLOAD_MB.

Models (env)

Variable	Default	Used for
GEMINI_MODEL	gemini-2.5-flash	Vision, orchestrator, SEO, text/shot verification
GEMINI_IMAGE_MODEL	gemini-3.1-flash-image-preview	Shot image output when ENABLE_IMAGE_GENERATION=1

Google’s dedicated image models (“Nano Banana”) are separate from general Flash; do not point image gen at GEMINI_MODEL.

Architecture

1. Vision — multimodal JSON from the product photo.
2. Classifier — maps to Turkish marketplace taxonomy (CATEGORIES.md) and fills listing attributes from photo + merchant text.
3. Orchestrator — theme + needs_manual; B2B catalog / channel_profile in prompt; allowed_themes clamp in Python.
4. Parallel text generation — SEO + creative shot plan (no images yet).
5. Verification orchestrator (agents/verification.py):
   • Text QA agent — rules engine + compact LLM on SEO and plan.
   • Repair loop (optional, verification_repair: true) — SEO and/or plan repair, max 2 rounds.
   • Image generation — parallel per-shot calls when a shot plan exists (ENABLE_IMAGE_GENERATION=1; independent of SEO text QA).
   • Shot QA agents (×N, parallel) — multimodal check per frame; minimal regen on minor issues (same shot_prompt + correction).
6. Response includes classification, verification.orchestration (text_rounds, shots_checked, shots_regenerated) and per-shot verification_passed when applicable.

Hackathon checklist: public GitHub repo, short project summary, 1-minute demo (curl against /v1/listings/generate), optional live API URL.

Submission note

Core engine: Google Gemini (google-genai). Workflow: LangGraph + verification orchestrator (bounded multi-agent QA). HTTP: FastAPI.