{"id":"45bd3721-4ef6-4de0-8754-044593d1cac0","entityType":"agent","slug":"clawhub-shapes-2-productai-skill","name":"Generate product photos for ecommerce","canonicalUrl":"https://www.xpersona.co/agent/clawhub-shapes-2-productai-skill","canonicalPath":"/agent/clawhub-shapes-2-productai-skill","generatedAt":"2026-10-11T15:19:58.022Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":null},"description":"Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma... Skill: Generate product photos for ecommerce Owner: shapes-2 Summary: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-02-24T13:03:31.529Z | user • Updated API documentation with all the official endpoints from your file • Added new models: kontext-max • Doc","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1786y733v1na5gqa9cw5sgq5d8a5qg4:productai-skill","sourceUrl":"https://clawhub.ai/shapes-2/productai-skill","homepage":"https://clawhub.ai/shapes-2/skills/productai-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/shapes-2/productai-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/shapes-2/skills/productai-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":null},"stars":null,"forks":null,"downloads":1071,"packageName":null,"latestVersion":"1.0.1","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:56:59.083Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T11:56:59.186Z","lastCrawledAt":"2026-10-11T11:56:59.083Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T11:56:59.083Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.1","createdAt":"2026-02-24T13:03:31.529Z","changelog":"• Updated API documentation with all the official endpoints from your file • Added new models: kontext-max • Documented aspect_ratio parameter with extended ratios for nanobanana models • Added resolution parameter (1K/2K/4K) • Complete error handling documentation • Created CHANGELOG.md to track versions","fileCount":18,"zipByteSize":38763},{"version":"1.0.0","createdAt":"2026-02-23T13:53:46.119Z","changelog":"First version","fileCount":16,"zipByteSize":36025}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1786y733v1na5gqa9cw5sgq5d8a5qg4:productai-skill","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T15:19:58.019Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-shapes-2-productai-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":null},"readme":"Skill: Generate product photos for ecommerce\n\nOwner: shapes-2\n\nSummary: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma...\n\nTags: latest:1.0.1\n\nVersion history:\n\nv1.0.1 | 2026-02-24T13:03:31.529Z | user\n\n• Updated API documentation with all the official endpoints from your file\n• Added new models: kontext-max\n• Documented aspect_ratio parameter with extended ratios for nanobanana models\n• Added resolution parameter (1K/2K/4K)\n• Complete error handling documentation\n• Created CHANGELOG.md to track versions\n\nv1.0.0 | 2026-02-23T13:53:46.119Z | user\n\nFirst version\n\nArchive index:\n\nArchive v1.0.1: 18 files, 38763 bytes\n\nFiles: CHANGELOG.md (1849b), config.example.json (181b), INTEGRATION-QUESTIONS.md (6069b), package.json (1013b), QUICKSTART.md (4539b), README.md (4097b), references/API.md (9638b), references/INTEGRATION_GUIDE.md (15542b), scripts/batch_generate.py (7864b), scripts/generate_photo.py (6855b), scripts/productai_client.py (9513b), scripts/setup.py (2756b), scripts/upscale_image.py (4359b), SECURITY.md (6367b), SETUP-GUIDE.md (6870b), skill-card.md (2618b), SKILL.md (7203b), _meta.json (134b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: productai\ndescription: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, marketing, catalogs, or campaigns. Supports background replacement, product placement, scene generation, adaptive templates, and video ads. Use for tasks involving product photography, lifestyle shots, mockups, or marketing visuals.\n---\n\n# ProductAI Integration\n\nProductAI.photo is an AI-powered service that generates professional product photos from existing images. It enables e-commerce businesses, marketers, and designers to create studio-quality product photography without hiring photographers.\n\n## Quick Start\n\n**1. Get Your API Key**\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your API key\n\n**2. Run Setup**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n# Paste your API key when prompted\n```\n\n**3. Generate Images**\n\n```bash\n# Generate product photo with custom background\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"modern living room with natural lighting\" \\\n  --output result.png\n\n# Use multiple reference images (nanobanana/seedream support 2 images)\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Put the first image on top of the second image\" \\\n  --output result.png\n\n# High quality with Nano Banana Pro\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"white studio background\" \\\n  --model nanobananapro \\\n  --output hq.png\n\n# Upscale an image (20 tokens)\nscripts/upscale_image.py \\\n  --image https://example.com/photo.jpg \\\n  --output upscaled.png\n```\n\n## Core Capabilities\n\n**Photo Generation (`/api/generate`)**\n- Background replacement with AI-generated scenes\n- Product placement in realistic environments\n- Multi-image compositing (up to 2 reference images with certain models)\n- Custom prompts for full creative control\n\n**Image Upscaling (`/api/upscale`)**\n- Professional AI upscaling (Magnific Precision Upscale)\n- Preserves image details without distortion\n- 20 tokens per upscale\n\n**Models Available**\n- **gpt-low** — GPT Low Quality (2 tokens)\n- **gpt-medium** — GPT Medium Quality (3 tokens)\n- **gpt-high** — GPT High Quality (8 tokens)\n- **kontext-pro** — Kontext Pro (3 tokens)\n- **nanobanana** — Nano Banana (3 tokens) — **DEFAULT**\n- **nanobananapro** — Nano Banana Pro (8 tokens)\n- **seedream** — Seedream (3 tokens)\n\n**Multi-Image Support:**\n`nanobanana`, `nanobananapro`, and `seedream` support up to 2 reference images for advanced compositing.\n\n## Configuration\n\n### API Setup\n\n**Step 1: Get Your API Key**\n\n1. Visit [ProductAI Studio](https://www.productai.photo)\n2. Navigate to **API Access** section\n3. Click **Generate API Key** or copy existing key\n\n**Step 2: Run Setup Script**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n```\n\nThis will interactively create `config.json` with your credentials:\n\n```json\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\nThe config file is automatically secured with 600 permissions.\n\n### Installation\n\nThe integration scripts require Python 3.7+ with these dependencies:\n\n```bash\npip install requests pillow\n```\n\nAll dependencies are handled automatically by the scripts.\n\n## Usage Examples\n\n### E-commerce Product Photos\n\nGenerate clean product shots for online stores:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/raw-product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output store-listing.png\n```\n\n### Marketing Campaign Visuals\n\nCreate lifestyle shots for advertising:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/bottle.jpg \\\n  --prompt \"outdoor picnic scene with blanket and basket, golden hour lighting\" \\\n  --output campaign-hero.png \\\n  --model kontext-pro\n```\n\n### Multi-Image Compositing\n\nCombine multiple products into one scene:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Place the lipstick on top of the cosmetics box\" \\\n  --model nanobanana \\\n  --output composite.png\n```\n\n### High-Quality Output\n\nUse Nano Banana Pro for premium results:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"luxury marble countertop setting with morning light\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n### Image Upscaling\n\nUpscale images for print or high-res displays:\n\n```bash\nscripts/upscale_image.py \\\n  --image https://example.com/product.jpg \\\n  --output upscaled.png\n```\n\n### Async Workflow (No Wait)\n\nStart generation and check later:\n\n```bash\n# Start job (prints job ID)\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"studio background\" \\\n  --no-wait\n\n# Output: Job created: 12345\n\n# Later, resume and download\nscripts/generate_photo.py \\\n  --job-id 12345 \\\n  --output result.png\n```\n\n## API Reference\n\nSee [API.md](references/API.md) for complete endpoint documentation, request/response formats, and authentication details.\n\n## Pricing & Token Costs\n\nProductAI uses a token-based pricing system:\n\n| Operation | Token Cost |\n|-----------|------------|\n| GPT Low Quality Generation | 2 tokens |\n| GPT Medium Quality Generation | 3 tokens |\n| GPT High Quality Generation | 8 tokens |\n| Kontext Pro | 3 tokens |\n| Nano Banana Pro | 8 tokens |\n| Nano Banana | 3 tokens |\n| Seedream | 3 tokens |\n| Magnific Precision Upscale | 20 tokens |\n\n**Subscription Plans:**\n\nVisit [ProductAI.photo](https://www.productai.photo) for current plans and token packages.\n\n**Rate Limits:**\n- 15 requests per minute\n- Daily limits based on subscription plan\n\n**Note:** Tokens are deducted when each operation **starts** (not on completion).\n\n## Troubleshooting\n\n**API Key Issues**\n- Verify `config.json` exists: `cat ~/.openclaw/workspace/productai/config.json`\n- Check API key in ProductAI Studio → API Access\n- Regenerate key if needed\n\n**OUT_OF_TOKENS Error**\n- Check your token balance in ProductAI Studio\n- Purchase more tokens or upgrade plan\n- Remember: tokens are deducted when jobs **start**, not on completion\n\n**Rate Limit (429)**\n- Maximum 15 requests per minute\n- Wait before retrying\n- Use `--no-wait` for batch jobs and check status later\n\n**Job Failed (ERROR status)**\n- Check image URL is accessible and under 10MB\n- Verify image format (PNG, JPG, or WebP only)\n- Check prompt length and content\n- Try a different model\n\n**Multi-Image Not Working**\n- Only `nanobanana`, `nanobananapro`, and `seedream` support multiple images\n- Maximum 2 reference images\n- Use array format: `--image url1 url2`\n\n## Support\n\n- Website: https://www.productai.photo\n- Documentation: See references/API.md\n- Contact: support@productai.photo (or team contact when available)\n\n## Advanced Topics\n\nFor detailed API specifications, authentication flows, webhook integration, and batch processing patterns, see [API.md](references/API.md).\n\nFile v1.0.1:README.md\n\n# ProductAI Integration for OpenClaw\n\nGenerate professional AI product photos directly from OpenClaw using the ProductAI.photo API.\n\n## What is ProductAI?\n\nProductAI.photo is an AI-powered service that transforms product images with:\n- Background replacement and scene generation\n- Multi-image compositing\n- Professional upscaling\n- Multiple AI models for different quality levels\n\nPerfect for e-commerce, marketing, and content creation.\n\n## Quick Links\n\n- **[ProductAI Website](https://www.productai.photo)** — Sign up & get API key\n- **[Quick Start Guide](QUICKSTART.md)** — Get running in 5 minutes\n- **[Setup Guide](SETUP-GUIDE.md)** — Detailed setup instructions & FAQ\n- **[Skill Documentation](SKILL.md)** — Full feature reference\n- **[API Reference](references/API.md)** — Complete API documentation\n\n## Installation\n\n### 1. Get Your API Key\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your key\n\n### 2. Run Setup\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nPaste your API key when prompted. That's it!\n\n### 3. Generate Images\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"white studio background\" \\\n  --output result.png\n```\n\n## Available Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `setup.py` | Configure API credentials |\n| `generate_photo.py` | Generate product photos |\n| `upscale_image.py` | Upscale images (20 tokens) |\n| `batch_generate.py` | Batch process multiple images |\n\n## Common Use Cases\n\n### Clean Product Backgrounds\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/messy.jpg\" \\\n  --prompt \"pure white background\" \\\n  --output clean.png\n```\n\n### Lifestyle Photography\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/watch.jpg\" \\\n  --prompt \"wrist wearing watch, business setting\" \\\n  --output lifestyle.png\n```\n\n### Multi-Image Compositing\n```bash\n./scripts/generate_photo.py \\\n  --image \"url1\" \"url2\" \\\n  --prompt \"Combine both products\" \\\n  --model nanobanana \\\n  --output combo.png\n```\n\n### High Quality (Nano Banana Pro)\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"luxury marble countertop\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n## Models & Pricing\n\n| Model | Cost | Quality |\n|-------|------|---------|\n| `gpt-low` | 2 tokens | Low |\n| `gpt-medium` | 3 tokens | Medium |\n| `nanobanana` | 3 tokens | **Recommended** |\n| `kontext-pro` | 3 tokens | Good |\n| `seedream` | 3 tokens | Creative |\n| `gpt-high` | 8 tokens | High |\n| `nanobananapro` | 8 tokens | Premium |\n| **Upscale** | 20 tokens | — |\n\n**Multi-image support:** `nanobanana`, `nanobananapro`, `seedream` (max 2 images)\n\n## Documentation\n\n- **New users:** Start with [QUICKSTART.md](QUICKSTART.md)\n- **Setup help:** See [SETUP-GUIDE.md](SETUP-GUIDE.md)\n- **Feature reference:** Read [SKILL.md](SKILL.md)\n- **API details:** Check [API.md](references/API.md)\n- **Security:** See [SECURITY.md](SECURITY.md)\n\n## Troubleshooting\n\n**\"Config file not found\"**\n→ Run `./scripts/setup.py` first\n\n**\"OUT_OF_TOKENS\"**\n→ Purchase more tokens at [productai.photo](https://www.productai.photo)\n\n**\"Unauthorized\" (401)**\n→ Check your API key in ProductAI Studio → API Access\n\n**Rate limited (429)**\n→ Wait a minute (limit: 15 requests/minute)\n\nMore help in [SETUP-GUIDE.md](SETUP-GUIDE.md#troubleshooting)\n\n## Security Features\n\n✅ **HTTPS-only URLs** — Blocks HTTP to prevent insecure requests  \n✅ **SSRF Prevention** — Blocks private IPs and localhost  \n✅ **Request Timeouts** — All HTTP requests timeout after 30s  \n✅ **Rate Limiting** — Batch processing respects 15 req/min limit  \n✅ **Path Traversal Protection** — Sanitizes all filenames\n\nSee [SECURITY.md](SECURITY.md) for full details.\n\n## Support\n\n- **Website:** https://www.productai.photo\n- **Get API Key:** ProductAI Studio → API Access\n- **Issues:** Contact ProductAI support via dashboard\n\n---\n\n**Ready to create amazing product photos?** Start with [QUICKSTART.md](QUICKSTART.md)!\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn747nct6wegm6yhndknwfj27s81q02v\",\n  \"slug\": \"productai-skill\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1771938211529\n}\n\nFile v1.0.1:references/API.md\n\n# ProductAI API Reference\n\nComplete documentation for ProductAI.photo public API endpoints.\n\n## Base URL\n\n```\nhttps://api.productai.photo/v1\n```\n\n## Authentication\n\nAll API requests require authentication via the `x-api-key` header:\n\n```bash\ncurl -H \"x-api-key: YOUR_API_KEY\" https://api.productai.photo/v1/api/generate\n```\n\n**Rate Limiting:** 15 requests per minute per IP address.\n\n---\n\n## `/api/generate` — Generate AI Product Photos\n\nGenerate an AI-edited image from one or more input images with a text prompt.\n\n### Endpoint\n\n```\nPOST /api/generate\n```\n\n### Request Body\n\n| Field           | Type                   | Required | Description                                                                                                                                                                              |\n| --------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `image_url`     | `string` or `string[]` | Yes      | URL(s) of input image(s). Maximum 2 images.                                                                                                                                              |\n| `prompt`        | `string`               | Yes      | Text prompt describing the desired edit/generation.                                                                                                                                      |\n| `model`         | `string`               | Yes      | One of: `gpt-low`, `gpt-medium`, `gpt-high`, `kontext-pro`, `kontext-max`, `nanobanana`, `nanobananapro`, `seedream`                                                                    |\n| `output_format` | `string`               | No       | `\"png\"` (default) or `\"jpg\"` / `\"jpeg\"`                                                                                                                                                 |\n| `aspect_ratio`  | `string`               | No       | `\"SQUARE\"`, `\"LANDSCAPE\"`, `\"PORTRAIT\"`. For `nanobanana`/`nanobananapro` also supports: `\"LANDSCAPE_4_3\"`, `\"LANDSCAPE_5_4\"`, `\"SQUARE_1_1\"`, `\"PORTRAIT_4_5\"`, `\"PORTRAIT_3_4\"`, or direct ratios like `\"4:3\"`, `\"9:16\"`, etc. |\n| `resolution`    | `string`               | No       | For `nanobanana`/`nanobananapro` only: `\"1K\"`, `\"2K\"` (default), or `\"4K\"`                                                                                                               |\n\n### Models & Pricing\n\n| Model          | Credits | Engine        |\n| -------------- | ------- | ------------- |\n| `gpt-low`      | 2       | GPT (Lambda)  |\n| `gpt-medium`   | 3       | GPT (Lambda)  |\n| `gpt-high`     | 8       | GPT (Lambda)  |\n| `kontext-pro`  | 2       | FAL           |\n| `kontext-max`  | 3       | FAL           |\n| `nanobanana`   | 3       | FAL           |\n| `nanobananapro`| 8       | FAL           |\n| `seedream`     | 3       | FAL           |\n\n### Example Request (Single Image)\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/generate \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image_url\": \"https://example.com/photo.jpg\",\n    \"prompt\": \"Make the background a sunset beach\",\n    \"model\": \"nanobananapro\",\n    \"output_format\": \"png\",\n    \"aspect_ratio\": \"LANDSCAPE\",\n    \"resolution\": \"2K\"\n  }'\n```\n\n### Example Request (Multiple Images)\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/generate \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image_url\": [\"https://example.com/product1.jpg\", \"https://example.com/product2.jpg\"],\n    \"prompt\": \"Place the first product on top of the second product\",\n    \"model\": \"nanobanana\",\n    \"output_format\": \"png\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 12345,\n    \"status\": \"RUNNING\",\n    \"prompt\": \"Make the background a sunset beach\"\n  }\n}\n```\n\n**Note:** Generation is **asynchronous** — use the job ID to poll for completion via `/api/job/:jobId`.\n\n### Status Codes\n\n| Code | Meaning |\n|------|---------|\n| `200` | Job created successfully |\n| `400` | Invalid request (check image URLs, prompt, model) |\n| `401` | Invalid API key |\n| `429` | Rate limit exceeded (max 15 requests/minute) |\n| `402` | Insufficient tokens |\n| `500` | Server error |\n\n---\n\n## `/api/job/:jobId` — Check Job Status\n\nCheck the status of a generation job and retrieve the result.\n\n### Endpoint\n\n```\nGET /api/job/:jobId\n```\n\n### Authentication\n\nRequires `x-api-key` header. The job must belong to the authenticated user.\n\n### Example Request\n\n```bash\ncurl -H \"x-api-key: YOUR_API_KEY\" \\\n  https://api.productai.photo/v1/api/job/12345\n```\n\n### Response (In Progress)\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 12345,\n    \"status\": \"RUNNING\",\n    \"prompt\": \"Make the background a sunset beach\"\n  }\n}\n```\n\n### Response (Completed)\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 12345,\n    \"status\": \"COMPLETED\",\n    \"prompt\": \"Make the background a sunset beach\",\n    \"image_url\": \"https://cdn.productai.photo/generated/result.png\"\n  }\n}\n```\n\n### Job Status Values\n\n| Status | Description |\n|--------|-------------|\n| `NOT_STARTED` | Job queued but not processing yet |\n| `RUNNING` | Currently generating |\n| `COMPLETED` | Finished — `image_url` available |\n| `ERROR` | Failed — check logs or contact support |\n\n**Note:** The `image_url` field only appears when status is `\"COMPLETED\"`.\n\n---\n\n## `/api/upscale` — Upscale Image\n\nUpscale an image using Magnific Precision Upscale AI.\n\n### Endpoint\n\n```\nPOST /api/upscale\n```\n\n### Request Body\n\n| Field       | Type     | Required | Description |\n|-------------|----------|----------|-------------|\n| `image_url` | `string` | Yes      | URL of the image to upscale |\n\n### Example Request\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/upscale \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image_url\": \"https://example.com/photo.jpg\"\n  }'\n```\n\n### Response\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 67890,\n    \"status\": \"RUNNING\"\n  }\n}\n```\n\n**Cost:** 20 tokens per upscale operation.\n\nPoll `/api/job/:jobId` to retrieve the upscaled image URL when complete.\n\n---\n\n## `/api/generate-custom-model` — Generate with Custom Model\n\nGenerate images using a custom-trained model (e.g., brand-specific product models).\n\n### Endpoint\n\n```\nPOST /api/generate-custom-model\n```\n\n### Request Body\n\n| Field       | Type     | Required | Description |\n|-------------|----------|----------|-------------|\n| `image_url` | `string` | Yes      | URL of input image |\n| `prompt`    | `string` | Yes      | Generation prompt |\n| `model`     | `string` | Yes      | Custom model identifier (e.g., `custom-owesa-avatars`) |\n\n### Example Request\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/generate-custom-model \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image_url\": \"https://example.com/photo.jpg\",\n    \"prompt\": \"Transform into brand style\",\n    \"model\": \"custom-owesa-avatars\"\n  }'\n```\n\n### Response\n\nSame format as `/api/generate` — returns a job ID to poll for completion.\n\n---\n\n## `/api/key-check` — Validate API Key\n\nVerify that your API key is valid and check remaining token balance.\n\n### Endpoint\n\n```\nGET /api/key-check\n```\n\n### Example Request\n\n```bash\ncurl -H \"x-api-key: YOUR_API_KEY\" \\\n  https://api.productai.photo/v1/api/key-check\n```\n\n### Response\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"valid\": true,\n    \"tokens_remaining\": 1250,\n    \"plan\": \"standard\"\n  }\n}\n```\n\n---\n\n## Error Handling\n\nAll error responses follow this format:\n\n```json\n{\n  \"status\": \"ERROR\",\n  \"message\": \"Descriptive error message\",\n  \"code\": \"ERROR_CODE\"\n}\n```\n\n### Common Error Codes\n\n| Code | HTTP Status | Meaning |\n|------|-------------|---------|\n| `INVALID_API_KEY` | 401 | API key missing or invalid |\n| `OUT_OF_TOKENS` | 402 | Insufficient tokens in account |\n| `RATE_LIMIT_EXCEEDED` | 429 | More than 15 requests/minute |\n| `INVALID_IMAGE_URL` | 400 | Image URL inaccessible or invalid format |\n| `INVALID_MODEL` | 400 | Model name not recognized |\n| `JOB_NOT_FOUND` | 404 | Job ID doesn't exist or belongs to another user |\n\n---\n\n## Best Practices\n\n### Asynchronous Workflow\n\n1. **Submit job** via `/api/generate` or `/api/upscale`\n2. **Store job ID** from response\n3. **Poll `/api/job/:jobId`** every 3-5 seconds until status is `COMPLETED` or `ERROR`\n4. **Download result** from `image_url` field\n\n### Rate Limiting\n\n- Maximum **15 requests per minute** per IP\n- Use exponential backoff when hitting 429 errors\n- For batch operations, space out requests (4-5 seconds apart)\n\n### Image Requirements\n\n- **Formats:** PNG, JPG, JPEG, WebP\n- **Max size:** 10 MB\n- **Max images per request:** 2 (only with `nanobanana`, `nanobananapro`, `seedream`)\n- **URLs must be publicly accessible** (no authentication required)\n\n### Token Management\n\n- Tokens are deducted when jobs **start** (not on completion)\n- Check balance via `/api/key-check` before large batches\n- Failed jobs still consume tokens\n\n---\n\n## SDK & Integration Examples\n\nFor Python integration examples and helper scripts, see:\n- `scripts/generate_photo.py` — Complete generation workflow\n- `scripts/upscale_image.py` — Upscaling workflow\n- `references/INTEGRATION_GUIDE.md` — Advanced patterns\n\n---\n\n## Support\n\n- **API Issues:** support@productai.photo\n- **Documentation:** https://www.productai.photo/docs\n- **Status Page:** https://status.productai.photo\n\nFile v1.0.1:references/INTEGRATION_GUIDE.md\n\n# ProductAI Integration Guide\n\nComplete guide for integrating ProductAI into your applications, workflows, and AI agents.\n\n## Quick Start (5 minutes)\n\n### 1. Install the Skill\n\n```bash\n# If skill is packaged as .skill file\nopenclaw skills install productai.skill\n\n# Or clone directly\ngit clone https://github.com/your-org/productai-skill ~/.openclaw/workspace/productai\n```\n\n### 2. Configure API Credentials\n\n```bash\ncd ~/.openclaw/workspace/productai\npython3 scripts/setup.py\n```\n\nOr manually create `config.json`:\n\n```json\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nano-banana-2\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\n### 3. Test It\n\n```bash\n# Generate your first photo\nscripts/generate_photo.py \\\n  --image product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output result.png\n```\n\n**Done!** You now have ProductAI integrated.\n\n## Integration Patterns\n\n### Pattern 1: Command-Line Scripts\n\nBest for: Manual workflows, batch jobs, cron tasks\n\n```bash\n# Single photo generation\nscripts/generate_photo.py --image product.jpg --prompt \"modern living room\" --output result.png\n\n# Background replacement\nscripts/generate_photo.py --image product.jpg --background-replace --output clean.png\n\n# Batch processing\nscripts/batch_generate.py \\\n  --input-dir ./products \\\n  --output-dir ./processed \\\n  --template \"white background with subtle shadows\"\n```\n\n### Pattern 2: Python Library\n\nBest for: Python applications, Jupyter notebooks, automation scripts\n\n```python\nfrom productai_client import create_client\n\n# Initialize client\nclient = create_client()\n\n# Generate photo\nresult = client.generate(\n    image='product.jpg',\n    prompt='modern living room with natural lighting'\n)\n\n# Download result\nclient.download_result(result['image_url'], 'output.png')\n\nprint(f\"Credits used: {result['credits_used']}\")\nprint(f\"Processing time: {result['processing_time_ms']}ms\")\n```\n\n### Pattern 3: AI Agent Integration\n\nBest for: OpenClaw agents, LangChain, AutoGPT, other AI systems\n\n**OpenClaw Integration:**\n\nThe skill is auto-loaded when OpenClaw detects product photo tasks. Just ask:\n\n> \"Generate a professional product photo of this bottle in a modern kitchen setting\"\n\n**Custom Agent Integration:**\n\n```python\nimport subprocess\nimport json\n\ndef generate_product_photo(image_path: str, prompt: str) -> dict:\n    \"\"\"Call ProductAI from any AI agent.\"\"\"\n    result = subprocess.run(\n        [\n            'python3',\n            '/path/to/productai/scripts/generate_photo.py',\n            '--image', image_path,\n            '--prompt', prompt,\n            '--output', 'result.png'\n        ],\n        capture_output=True,\n        text=True\n    )\n    \n    return json.loads(result.stdout)\n\n# Use in your agent\nresult = generate_product_photo('product.jpg', 'white background')\nprint(f\"Generated: {result['image_url']}\")\n```\n\n### Pattern 4: REST API Wrapper\n\nBest for: Microservices, web apps, team access\n\n```python\nfrom flask import Flask, request, jsonify\nfrom productai_client import create_client\n\napp = Flask(__name__)\nclient = create_client()\n\n@app.route('/api/generate', methods=['POST'])\ndef generate():\n    data = request.json\n    \n    result = client.generate(\n        image=data['image'],\n        prompt=data['prompt'],\n        model=data.get('model', 'nano-banana-2')\n    )\n    \n    return jsonify(result)\n\n@app.route('/api/background-replace', methods=['POST'])\ndef background_replace():\n    data = request.json\n    \n    result = client.background_replace(\n        image=data['image'],\n        background_type=data.get('background_type', 'white')\n    )\n    \n    return jsonify(result)\n\nif __name__ == '__main__':\n    app.run(port=5000)\n```\n\n## Real-World Use Cases\n\n### E-Commerce Product Photos\n\n**Challenge:** Need 1000 product photos with consistent white backgrounds for Shopify store.\n\n**Solution:**\n\n```bash\n# 1. Organize products\nmkdir -p products/raw products/processed\n\n# 2. Batch process with white background\nscripts/batch_generate.py \\\n  --input-dir products/raw \\\n  --output-dir products/processed \\\n  --template \"clean white background with soft drop shadow\" \\\n  --max-workers 5\n\n# 3. Upload to Shopify (use Shopify API or bulk upload)\n```\n\n**Result:** Professional product photos at 10x lower cost than photographer.\n\n### Marketing Campaign Visuals\n\n**Challenge:** Create lifestyle product shots for Instagram campaign.\n\n**Solution:**\n\n```python\nfrom productai_client import create_client\n\nclient = create_client()\n\nscenes = [\n    \"product on rustic wooden table with morning coffee\",\n    \"product held in hands outdoors with natural lighting\",\n    \"product on modern desk with laptop and plant\",\n    \"product on kitchen counter with fresh ingredients\"\n]\n\nfor i, scene in enumerate(scenes):\n    result = client.generate(\n        image='product.jpg',\n        prompt=scene,\n        model='flux-kontext',\n        resolution='1024x1024'\n    )\n    \n    client.download_result(\n        result['image_url'],\n        f'campaign/instagram_{i+1}.png'\n    )\n    \n    print(f\"✓ Generated scene {i+1}: {scene}\")\n```\n\n**Result:** 4 unique lifestyle shots ready for social media in minutes.\n\n### Product Catalog Updates\n\n**Challenge:** Seasonal catalog needs all products re-shot with holiday theme.\n\n**Solution:**\n\n```bash\n# Generate holiday-themed versions\nscripts/batch_generate.py \\\n  --input-dir catalog/products \\\n  --output-dir catalog/holiday \\\n  --template \"festive holiday setting with warm lighting and decorations\" \\\n  --model nano-banana-2-pro\n\n# Or summer theme\nscripts/batch_generate.py \\\n  --input-dir catalog/products \\\n  --output-dir catalog/summer \\\n  --template \"bright summer outdoor setting with natural sunlight\"\n```\n\n**Result:** Entire catalog refreshed for new season without re-shooting products.\n\n### Automated Listing Generator\n\n**Challenge:** Automatically create marketplace listings with professional photos.\n\n**Solution:**\n\n```python\nfrom productai_client import create_client\nimport csv\n\nclient = create_client()\n\n# Read product inventory\nwith open('inventory.csv') as f:\n    products = csv.DictReader(f)\n    \n    for product in products:\n        # Generate professional photo\n        result = client.generate(\n            image=product['raw_photo_url'],\n            prompt='clean white background for e-commerce',\n            model='nano-banana-2'\n        )\n        \n        # Download and save\n        output_path = f\"listings/{product['sku']}.png\"\n        client.download_result(result['image_url'], output_path)\n        \n        # Create listing (pseudo-code)\n        create_marketplace_listing(\n            title=product['name'],\n            image=output_path,\n            price=product['price']\n        )\n        \n        print(f\"✓ Listed {product['name']}\")\n```\n\n**Result:** Fully automated listing creation with professional photos.\n\n## Advanced Topics\n\n### Custom Webhooks\n\nGet notified when batch jobs complete:\n\n```python\nfrom flask import Flask, request\nfrom productai_client import create_client\n\napp = Flask(__name__)\nclient = create_client()\n\n@app.route('/webhook/productai', methods=['POST'])\ndef productai_webhook():\n    event = request.json\n    \n    if event['event'] == 'job.completed':\n        job_id = event['job_id']\n        result_url = event['result']['image_url']\n        \n        # Process completed job\n        client.download_result(result_url, f'results/{job_id}.png')\n        \n        # Trigger next step in workflow\n        process_completed_image(job_id)\n    \n    return '', 200\n\n# Submit async batch\nresult = client.batch_generate(\n    images=['product1.jpg', 'product2.jpg'],\n    template='white background',\n    webhook_url='https://your-server.com/webhook/productai'\n)\n\nbatch_id = result['batch_id']\nprint(f\"Batch submitted: {batch_id}\")\n```\n\n### Credit Management\n\nMonitor and optimize credit usage:\n\n```python\nfrom productai_client import create_client\n\nclient = create_client()\n\n# Track credits\ntotal_credits = 0\nresults = []\n\nfor image in product_images:\n    result = client.generate(image=image, prompt='white background')\n    \n    credits_used = result['credits_used']\n    total_credits += credits_used\n    results.append(result)\n    \n    print(f\"Processed {image}: {credits_used} credits\")\n\nprint(f\"Total credits used: {total_credits}\")\nprint(f\"Average per image: {total_credits / len(product_images):.2f}\")\n```\n\n**Optimization tips:**\n- Use lower resolution for thumbnails\n- Batch similar products to save credits\n- Cache generated images\n- Use Basic plan for simple backgrounds, Pro for high-end\n\n### Quality Control\n\nImplement QA checks on generated images:\n\n```python\nfrom PIL import Image\nimport requests\nfrom productai_client import create_client\n\nclient = create_client()\n\ndef check_image_quality(image_url: str) -> dict:\n    \"\"\"Basic quality checks on generated image.\"\"\"\n    response = requests.get(image_url)\n    img = Image.open(BytesIO(response.content))\n    \n    width, height = img.size\n    aspect_ratio = width / height\n    \n    # Check resolution\n    if width < 1000 or height < 1000:\n        return {'status': 'low_resolution', 'width': width, 'height': height}\n    \n    # Check aspect ratio (for square products)\n    if not (0.9 < aspect_ratio < 1.1):\n        return {'status': 'wrong_aspect_ratio', 'ratio': aspect_ratio}\n    \n    return {'status': 'ok'}\n\n# Generate with QA\nresult = client.generate(\n    image='product.jpg',\n    prompt='white background',\n    resolution='1024x1024'\n)\n\nqa_result = check_image_quality(result['image_url'])\nif qa_result['status'] == 'ok':\n    client.download_result(result['image_url'], 'approved.png')\nelse:\n    print(f\"Quality issue: {qa_result}\")\n    # Retry or flag for manual review\n```\n\n### Template Management\n\nCreate reusable templates for consistent brand styling:\n\n```python\n# templates.py\nTEMPLATES = {\n    'ecommerce_white': 'clean white background with soft drop shadow',\n    'ecommerce_grey': 'light grey gradient background',\n    'lifestyle_home': 'modern home interior with natural lighting',\n    'lifestyle_outdoor': 'outdoor setting with natural environment',\n    'hands_holding': 'product held in hands with professional lighting',\n    'table_flat_lay': 'flat lay on white marble table with props'\n}\n\n# Use templates\nfrom productai_client import create_client\n\nclient = create_client()\n\nresult = client.generate(\n    image='product.jpg',\n    prompt=TEMPLATES['lifestyle_home'],\n    model='flux-kontext'\n)\n```\n\n### Error Handling & Retries\n\nRobust error handling for production:\n\n```python\nimport time\nfrom productai_client import create_client, ProductAIClient\nimport requests\n\ndef generate_with_retry(\n    client: ProductAIClient,\n    image: str,\n    prompt: str,\n    max_retries: int = 3\n) -> dict:\n    \"\"\"Generate with exponential backoff retry.\"\"\"\n    \n    for attempt in range(max_retries):\n        try:\n            result = client.generate(image=image, prompt=prompt)\n            return result\n            \n        except requests.exceptions.HTTPError as e:\n            if e.response.status_code == 429:\n                # Rate limited\n                wait = 2 ** attempt\n                print(f\"Rate limited. Waiting {wait}s...\")\n                time.sleep(wait)\n                continue\n            \n            elif e.response.status_code == 402:\n                # Insufficient credits\n                raise Exception(\"Out of credits\")\n            \n            elif attempt == max_retries - 1:\n                # Last attempt, give up\n                raise\n            \n            else:\n                # Other error, retry\n                wait = 2 ** attempt\n                time.sleep(wait)\n                continue\n        \n        except requests.exceptions.RequestException as e:\n            # Network error\n            if attempt == max_retries - 1:\n                raise\n            \n            wait = 2 ** attempt\n            print(f\"Network error. Retrying in {wait}s...\")\n            time.sleep(wait)\n            continue\n    \n    raise Exception(\"Max retries exceeded\")\n\n# Use it\nclient = create_client()\nresult = generate_with_retry(client, 'product.jpg', 'white background')\n```\n\n## Performance Optimization\n\n### Parallel Processing\n\n```python\nfrom concurrent.futures import ThreadPoolExecutor, as_completed\nfrom productai_client import create_client\n\nclient = create_client()\n\ndef process_product(image_path: str, template: str) -> dict:\n    result = client.generate(image=image_path, prompt=template)\n    return {'input': image_path, 'result': result}\n\n# Process 100 products in parallel (respect rate limits)\nwith ThreadPoolExecutor(max_workers=5) as executor:\n    futures = {\n        executor.submit(process_product, img, 'white background'): img\n        for img in product_images\n    }\n    \n    for future in as_completed(futures):\n        result = future.result()\n        print(f\"✓ Processed {result['input']}\")\n```\n\n### Caching Strategy\n\n```python\nimport hashlib\nimport json\nfrom pathlib import Path\n\nCACHE_DIR = Path('cache/productai')\nCACHE_DIR.mkdir(parents=True, exist_ok=True)\n\ndef get_cache_key(image: str, prompt: str, **kwargs) -> str:\n    \"\"\"Generate cache key from parameters.\"\"\"\n    params = {'image': image, 'prompt': prompt, **kwargs}\n    key_string = json.dumps(params, sort_keys=True)\n    return hashlib.md5(key_string.encode()).hexdigest()\n\ndef cached_generate(client, image: str, prompt: str, **kwargs) -> dict:\n    \"\"\"Generate with caching.\"\"\"\n    cache_key = get_cache_key(image, prompt, **kwargs)\n    cache_file = CACHE_DIR / f\"{cache_key}.json\"\n    \n    # Check cache\n    if cache_file.exists():\n        print(f\"Cache hit: {cache_key}\")\n        return json.loads(cache_file.read_text())\n    \n    # Generate\n    result = client.generate(image=image, prompt=prompt, **kwargs)\n    \n    # Cache result\n    cache_file.write_text(json.dumps(result, indent=2))\n    \n    return result\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue:** `Configuration file not found`\n\n**Solution:**\n```bash\ncd ~/.openclaw/workspace/productai\npython3 scripts/setup.py\n```\n\n---\n\n**Issue:** `API Error 401: Unauthorized`\n\n**Solution:** Check your API key in `config.json` is correct.\n\n---\n\n**Issue:** `API Error 402: Insufficient credits`\n\n**Solution:** Your plan has run out of credits. Upgrade or wait for monthly reset.\n\n---\n\n**Issue:** `API Error 429: Rate limit exceeded`\n\n**Solution:** Reduce `max_workers` in batch jobs or add delays between requests.\n\n---\n\n**Issue:** Generated images don't match prompt\n\n**Solution:** \n- Make prompts more specific\n- Try different models (flux-kontext for placement, nano-banana-2-pro for quality)\n- Adjust scale parameter\n\n---\n\n**Issue:** Batch processing too slow\n\n**Solution:**\n- Increase `max_workers` (respect rate limits)\n- Use async batch API with webhooks instead of polling\n- Parallelize with multiple API keys if allowed\n\n## Support & Resources\n\n- **Documentation:** `references/API.md`\n- **Website:** https://www.productai.photo\n- **Email:** support@productai.photo\n- **Discord:** (when available)\n\n## Contributing\n\nTo contribute improvements to this integration:\n\n1. Fork the skill repository\n2. Make your changes\n3. Test thoroughly\n4. Submit pull request with description\n\n**Areas for contribution:**\n- Additional language bindings (JS, Ruby, Go)\n- Enhanced error handling\n- Performance optimizations\n- New templates and presets\n- Integration examples\n\n## License\n\nThis integration skill is provided as-is for use with ProductAI service.\nCheck ProductAI's terms of service for API usage terms.\n\nFile v1.0.1:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the ProductAI skill will be documented in this file.\n\n## [1.2.0] - 2026-02-24\n\n### Updated\n- **API Reference Documentation** — Complete rewrite of `references/API.md` with official ProductAI API endpoints\n- Added detailed documentation for `/api/generate` endpoint with all parameters\n- Added `/api/job/:jobId` polling endpoint documentation\n- Added `/api/upscale` endpoint details\n- Added `/api/generate-custom-model` endpoint for custom model support\n- Added `/api/key-check` endpoint for API key validation\n- Documented new models: `kontext-max`, updated pricing table\n- Added `aspect_ratio` parameter support with extended ratio options for nanobanana/nanobananapro\n- Added `resolution` parameter documentation (1K/2K/4K) for nanobanana models\n- Improved error handling documentation with specific error codes\n- Added best practices section for async workflows and rate limiting\n\n### Technical Details\n- Models now include: `gpt-low`, `gpt-medium`, `gpt-high`, `kontext-pro`, `kontext-max`, `nanobanana`, `nanobananapro`, `seedream`\n- Rate limit: 15 requests per minute per IP\n- Multi-image support: up to 2 images with `nanobanana`, `nanobananapro`, `seedream`\n- Output formats: PNG (default), JPG/JPEG\n- Aspect ratios: Standard (SQUARE/LANDSCAPE/PORTRAIT) + extended ratios for nano models\n\n## [1.1.0] - 2026-02-23\n\n### Added\n- Initial release with core functionality\n- Image generation with multiple model support\n- Image upscaling support\n- Multi-image compositing (up to 2 images)\n- Async job polling\n- Setup wizard for API key configuration\n- Comprehensive documentation and examples\n\n### Features\n- `generate_photo.py` — Generate AI product photos\n- `upscale_image.py` — Upscale images with Magnific AI\n- `batch_generate.py` — Batch processing support\n- `setup.py` — Interactive setup wizard\n\nFile v1.0.1:INTEGRATION-QUESTIONS.md\n\n# ProductAI Integration - Questions for Users\n\nThis document contains the key questions to ask users when setting up ProductAI integration, along with the easiest setup flow.\n\n---\n\n## Pre-Integration Questions\n\n### 1. Do you have a ProductAI account?\n\n**If NO:**\n- Direct them to: **[https://www.productai.photo](https://www.productai.photo)**\n- They need to sign up and choose a plan (Basic, Standard, or Pro)\n- Wait for them to complete signup\n\n**If YES:**\n- Proceed to question 2\n\n---\n\n### 2. Do you have a ProductAI API key?\n\n**If NO:**\n- Guide them: \"Go to ProductAI Studio → **API Access** → Generate API Key\"\n- Wait for them to copy the key\n- **Important:** Remind them to keep it secret!\n\n**If YES:**\n- Ask them to have it ready (they'll paste it in setup)\n\n---\n\n### 3. What plan are you on?\n\nOptions:\n- **Basic** ($8/month) — 70 + 20 free credits\n- **Standard** ($16/month) — 250 + 20 free credits\n- **Pro** ($49/month) — 950 + 20 free credits\n\nThis helps set expectations for token usage.\n\n---\n\n### 4. What will you use ProductAI for?\n\nCommon answers:\n- E-commerce product photos (clean backgrounds, lifestyle shots)\n- Marketing campaigns (hero images, social media)\n- Batch processing product catalogs\n- Creative compositing (multi-image scenes)\n- Image upscaling for print/high-res\n\nThis helps recommend the right model and workflow.\n\n---\n\n## Super Easy Setup Flow\n\n### Step 1: Verify They Have an API Key\n\n```\nAgent: \"To use ProductAI, you'll need an API key. Do you have one?\"\n\nUser: \"No\" → Guide to productai.photo, wait\nUser: \"Yes\" → Proceed\n```\n\n---\n\n### Step 2: Run Setup\n\n**Option A: Interactive (User runs script)**\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nThe script asks:\n1. **API Key:** User pastes key\n2. **API Endpoint:** [Press Enter for default]\n3. **Default Model:** [Press Enter for nanobanana]\n4. **Default Resolution:** [Press Enter for 1024x1024]\n5. **Your Plan:** basic / standard / pro\n\n**Option B: Agent-Driven (Programmatic)**\n\n```python\n# Agent collects API key in conversation\napi_key = user_message  # e.g., \"sk_prod_abc123...\"\n\n# Agent creates config\nimport json\nfrom pathlib import Path\n\nconfig = {\n    \"api_key\": api_key,\n    \"api_endpoint\": \"https://api.productai.photo/v1\",\n    \"default_model\": \"nanobanana\",\n    \"default_resolution\": \"1024x1024\",\n    \"plan\": \"standard\"  # Or ask user\n}\n\nconfig_path = Path.home() / '.openclaw' / 'workspace' / 'productai' / 'config.json'\nconfig_path.parent.mkdir(parents=True, exist_ok=True)\n\nwith open(config_path, 'w') as f:\n    json.dump(config, f, indent=2)\n\nconfig_path.chmod(0o600)\n\n# Confirm to user\nprint(\"✓ ProductAI configured! Your API key is saved securely.\")\n```\n\n---\n\n### Step 3: Test It Immediately\n\n**Run a quick test to confirm setup works:**\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://i.imgur.com/sample.jpg\" \\\n  --prompt \"white background\" \\\n  --output test.png\n```\n\n**If successful:**\n```\n✓ Job created: 12345\nWaiting for completion...\n✓ Generation complete!\nDownloading image to test.png...\n✓ Saved to test.png\n```\n\n**If failed:**\n- `401 Unauthorized` → Invalid API key (ask user to regenerate)\n- `OUT_OF_TOKENS` → No credits left (ask user to purchase more)\n- Other errors → Check error message and guide user\n\n---\n\n## Making API Key Input Super Easy\n\n### Best Practices\n\n**✅ DO:**\n1. **Provide direct link:** \"Get your key here: [https://www.productai.photo/api-access](https://www.productai.photo)\"\n2. **Show exactly where to find it:** \"Look for **API Access** in your dashboard\"\n3. **Auto-validate:** Test the API key immediately after setup\n4. **Give clear feedback:** \"✓ API key valid!\" or \"❌ Invalid key, please check and try again\"\n5. **Secure it automatically:** Set file permissions to 600 (user-only read/write)\n\n**❌ DON'T:**\n1. Ask for info you can auto-detect (API endpoint, default model)\n2. Show raw JSON or complex config formats\n3. Leave users wondering if setup worked (always test!)\n4. Display the API key in logs or responses (security!)\n\n---\n\n## Sample Conversation Flow\n\n```\nAgent: \"Ready to set up ProductAI! Do you have an API key?\"\n\nUser: \"No\"\n\nAgent: \"No problem! Here's what to do:\n\n1. Visit https://www.productai.photo\n2. Log in (or sign up if you're new)\n3. Go to **API Access**\n4. Copy your API key\n\nLet me know when you have it!\"\n\n---\n\nUser: \"Got it: sk_prod_abc123xyz\"\n\nAgent: \"Perfect! Setting that up now...\"\n[Creates config.json programmatically]\n\nAgent: \"✓ API key saved securely!\n\nWant to test it? Send me a product image URL and I'll generate \na version with a clean white background.\"\n\n---\n\nUser: \"https://example.com/watch.jpg\"\n\nAgent: [Runs generate_photo.py]\n\"Here's your product with a white studio background! 🎨\n[Sends generated image]\n\nCost: 3 tokens (Nano Banana model)\n\nWhat else would you like to create?\"\n```\n\n---\n\n## Error Recovery\n\n### Invalid API Key (401)\n\n```\nAgent: \"Hmm, that API key didn't work. Here's what to check:\n\n1. Make sure you copied the full key (starts with 'sk_prod_')\n2. Verify it's active in ProductAI Studio → API Access\n3. Try regenerating a new key if needed\n\nWant to try again?\"\n```\n\n---\n\n### Out of Tokens\n\n```\nAgent: \"You're out of tokens! Here's how to get more:\n\n- **Purchase tokens:** Visit productai.photo\n- **Upgrade plan:** Get more monthly credits with Standard or Pro\n\nYour current plan: [plan]\n\nLet me know when you're ready to continue!\"\n```\n\n---\n\n### Rate Limited (429)\n\n```\nAgent: \"ProductAI has a rate limit of 15 requests/minute. \nLet's wait a moment before trying again...\"\n\n[Auto-retry after 10 seconds]\n```\n\n---\n\n## Key Takeaways\n\n1. **Minimize friction:** Only ask what you absolutely need (API key, plan)\n2. **Validate immediately:** Test the API key right after setup\n3. **Provide clear guidance:** Direct links, step-by-step, screenshots\n4. **Handle errors gracefully:** Clear messages + recovery steps\n5. **Make it conversational:** Feel like talking to a helpful human\n\n---\n\n**Goal:** User gets from \"I want to use ProductAI\" to \"Here's my first generated image\" in under 2 minutes.\n\nFile v1.0.1:QUICKSTART.md\n\n# ProductAI Quick Start Guide\n\nGet started with ProductAI in 5 minutes.\n\n## Step 1: Get Your API Key\n\n1. Visit **[ProductAI Studio](https://www.productai.photo)**\n2. Click on **API Access** in the navigation\n3. Find or generate your API key\n4. Copy it to clipboard\n\n> **Where to find it:**\n> \n> ![API Access Screenshot - Shows where to find your API key in the ProductAI dashboard]\n\n## Step 2: Run Setup\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nWhen prompted:\n- **API Key:** Paste your key from Step 1\n- **API Endpoint:** Press Enter (uses default: `https://api.productai.photo/v1`)\n- **Default Model:** Press Enter (uses `nanobanana`)\n- **Default Resolution:** Press Enter (uses `1024x1024`)\n- **Your Plan:** Enter your plan (`basic`, `standard`, or `pro`)\n\nThe setup script will:\n- Create `config.json` with your settings\n- Secure the file (permissions: 600)\n- Confirm everything is ready\n\n## Step 3: Generate Your First Image\n\nTry a simple generation:\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/your-product.jpg\" \\\n  --prompt \"white studio background with soft lighting\" \\\n  --output my-first-result.png\n```\n\n**What happens:**\n1. API request sent to ProductAI\n2. Job created (you'll see the job ID)\n3. Script polls for completion (~5-30 seconds)\n4. Image downloads to `my-first-result.png`\n\n## Common Use Cases\n\n### Clean Product Backgrounds\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/messy-bg.jpg\" \\\n  --prompt \"pure white background\" \\\n  --output clean.png\n```\n\n### Lifestyle Shots\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/watch.jpg\" \\\n  --prompt \"wrist wearing the watch, business attire, office desk background\" \\\n  --output lifestyle.png\n```\n\n### Combine Multiple Products\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/lipstick.jpg\" \"https://example.com/box.jpg\" \\\n  --prompt \"Place the lipstick on top of the cosmetic box\" \\\n  --model nanobanana \\\n  --output combo.png\n```\n\n### High Quality (Nano Banana Pro)\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"luxury marble countertop, golden hour lighting\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n> **Note:** Nano Banana Pro costs 8 tokens vs 3 for regular models\n\n### Upscale for Print\n\n```bash\n./scripts/upscale_image.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --output upscaled.png\n```\n\n> **Note:** Upscaling costs 20 tokens\n\n## Available Models\n\n| Model | Token Cost | Best For |\n|-------|------------|----------|\n| `gpt-low` | 2 | Quick tests, drafts |\n| `gpt-medium` | 3 | Standard quality |\n| `gpt-high` | 8 | High quality |\n| `kontext-pro` | 3 | Product placement |\n| `nanobanana` | 3 | **Default** — fast & good |\n| `nanobananapro` | 8 | Premium quality |\n| `seedream` | 3 | Creative scenes |\n\n**Multi-image support:** `nanobanana`, `nanobananapro`, `seedream` (max 2 images)\n\n## Async Workflow (For Batch Jobs)\n\nInstead of waiting for each job, start them all and check later:\n\n```bash\n# Start 3 jobs (collect job IDs)\n./scripts/generate_photo.py --image \"url1\" --prompt \"prompt1\" --no-wait  # → Job ID: 101\n./scripts/generate_photo.py --image \"url2\" --prompt \"prompt2\" --no-wait  # → Job ID: 102\n./scripts/generate_photo.py --image \"url3\" --prompt \"prompt3\" --no-wait  # → Job ID: 103\n\n# Later, download results\n./scripts/generate_photo.py --job-id 101 --output result1.png\n./scripts/generate_photo.py --job-id 102 --output result2.png\n./scripts/generate_photo.py --job-id 103 --output result3.png\n```\n\n## Troubleshooting\n\n### \"Config file not found\"\nRun `./scripts/setup.py` first.\n\n### \"OUT_OF_TOKENS\"\nCheck your token balance in ProductAI Studio. Purchase more tokens or upgrade plan.\n\n### \"Invalid API key\" (401)\nRegenerate your API key in ProductAI Studio → API Access.\n\n### Job stuck at \"RUNNING\"\nJobs usually complete in 5-30 seconds. If stuck after 5 minutes, check ProductAI Studio for service status.\n\n### Image not downloaded\nCheck that the image URL is publicly accessible and under 10MB (PNG, JPG, or WebP).\n\n## Next Steps\n\n- Read [SKILL.md](SKILL.md) for full feature documentation\n- Check [API.md](references/API.md) for detailed API reference\n- Explore batch processing with `batch_generate.py`\n- Set up webhooks for production workflows\n\n## Support\n\n- **Website:** https://www.productai.photo\n- **API Docs:** [references/API.md](references/API.md)\n- **Issues:** Contact ProductAI support via dashboard\n\n---\n\n**Happy generating! 🚀**\n\nFile v1.0.1:SECURITY.md\n\n# Security Features & Mitigations\n\nThis document outlines the security measures implemented in the ProductAI skill.\n\n## Security Fixes Applied\n\n### ✅ Fixed Issues\n\n#### 1. URL Validation & SSRF Prevention\n**Issue:** Image URLs accepted without validation, potential SSRF attacks  \n**Fix:** `productai_client.py:validate_image_url()`\n- **HTTPS-only:** Rejects HTTP URLs\n- **Private network blocking:** Prevents access to:\n  - localhost / 127.x.x.x\n  - Private IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x)\n  - Link-local addresses (169.254.x.x)\n  - IPv6 localhost/link-local (::1, fe80::)\n- Applied to all image URL inputs in `generate()` and `upscale()`\n\n#### 2. Request Timeouts\n**Issue:** HTTP requests without timeouts could hang indefinitely  \n**Fix:** Added 30-second timeout to all requests:\n- `productai_client.py`: All API calls (`DEFAULT_TIMEOUT = 30`)\n- `generate_photo.py`: Image downloads\n- `upscale_image.py`: Image downloads\n- `batch_generate.py`: Image downloads\n\n#### 3. Rate Limiting (Batch Processing)\n**Issue:** No rate limiting despite 15 req/min API limit  \n**Fix:** `batch_generate.py`\n- Enforces 4-second minimum between requests (15 req/min = 4s interval)\n- Default max workers: 3 (to stay comfortably under limit)\n- Sequential request submission with `time.sleep()` between requests\n\n#### 4. Path Traversal Prevention\n**Issue:** Unsanitized filenames in batch processing  \n**Fix:** `batch_generate.py:sanitize_filename()`\n- Removes path separators (`/`, `\\`)\n- Blocks parent directory references (`..`)\n- Allows only alphanumeric, dash, underscore, dot\n- Prevents hidden files (leading `.`)\n\n---\n\n## Acceptable Trade-offs\n\n### Plain Text API Key Storage\n**Rationale:**\n- Industry standard for CLI tools (AWS CLI, gcloud, stripe-cli all do this)\n- File permissions set to `600` (user read/write only)\n- Alternative (OS keychain) adds complexity and dependencies\n- Users can use environment variables if preferred: `PRODUCTAI_API_KEY`\n\n**Mitigation:**\n- Config file: `chmod 600` (user-only access)\n- API key never logged or displayed in output\n- Clear documentation warns users to keep keys secure\n\n---\n\n## Security Best Practices for Users\n\n### 1. Protect Your API Key\n- Never commit `config.json` to version control\n- Don't share your API key in chat, logs, or screenshots\n- Regenerate key if accidentally exposed\n\n### 2. Use HTTPS URLs Only\n- The skill enforces HTTPS-only image URLs\n- Avoids exposing API keys over unencrypted connections\n\n### 3. Monitor API Usage\n- Check ProductAI dashboard regularly for unexpected usage\n- Rate limits prevent runaway costs\n\n### 4. Keep Dependencies Updated\n- Run `pip install --upgrade requests` periodically\n- Monitor security advisories for Python dependencies\n\n---\n\n## Implementation Details\n\n### URL Validation (`productai_client.py`)\n\n```python\n@staticmethod\ndef validate_image_url(url: str) -> None:\n    \"\"\"Validate image URL for security.\"\"\"\n    parsed = urlparse(url)\n    \n    # Only allow HTTPS\n    if parsed.scheme != 'https':\n        raise ValueError(f\"Only HTTPS URLs are allowed. Got: {parsed.scheme}://\")\n    \n    # Block private/local network addresses (SSRF prevention)\n    hostname = parsed.hostname\n    if not hostname:\n        raise ValueError(\"Invalid URL: missing hostname\")\n    \n    # Block localhost, private IPs, link-local\n    blocked_patterns = [\n        r'^localhost$',\n        r'^127\\.',\n        r'^10\\.',\n        r'^172\\.(1[6-9]|2[0-9]|3[01])\\.',\n        r'^192\\.168\\.',\n        r'^169\\.254\\.',\n        r'^::1$',\n        r'^fe80:',\n    ]\n    \n    for pattern in blocked_patterns:\n        if re.match(pattern, hostname, re.IGNORECASE):\n            raise ValueError(f\"Private/local addresses are not allowed: {hostname}\")\n```\n\n### Request Timeouts\n\nAll HTTP requests include explicit timeouts:\n\n```python\n# API calls\nresponse = self.session.post(url, json=payload, timeout=30)\n\n# Image downloads\nresponse = requests.get(url, stream=True, timeout=30)\n```\n\n### Rate Limiting (`batch_generate.py`)\n\n```python\nRATE_LIMIT_SECONDS = 4.0  # 15 req/min = 4s interval\n\nfor image_url in image_urls:\n    # Rate limiting: ensure minimum time between requests\n    elapsed = time.time() - last_request_time\n    if elapsed < RATE_LIMIT_SECONDS:\n        time.sleep(RATE_LIMIT_SECONDS - elapsed)\n    \n    # Submit job\n    future = executor.submit(process_single_image, ...)\n    last_request_time = time.time()\n```\n\n### Filename Sanitization (`batch_generate.py`)\n\n```python\ndef sanitize_filename(filename: str) -> str:\n    \"\"\"Sanitize filename to prevent path traversal.\"\"\"\n    # Remove path separators and parent references\n    safe_name = filename.replace('/', '_').replace('\\\\', '_').replace('..', '_')\n    \n    # Keep only safe characters\n    safe_name = re.sub(r'[^a-zA-Z0-9._-]', '_', safe_name)\n    \n    # Prevent hidden files\n    if safe_name.startswith('.'):\n        safe_name = '_' + safe_name[1:]\n    \n    return safe_name\n```\n\n---\n\n## Testing\n\nAll security fixes have been tested:\n\n### URL Validation Tests\n```bash\n✓ Valid HTTPS URL accepted\n✓ HTTP blocked: Only HTTPS URLs are allowed. Got: http://\n✓ Localhost blocked: Private/local addresses are not allowed: localhost\n✓ Private IP blocked: Private/local addresses are not allowed: 192.168.1.1\n```\n\n### Filename Sanitization Tests\n```bash\n✓ \"normal.jpg\" → \"normal.jpg\"\n✓ \"../../../etc/passwd\" → \"______etc_passwd\"\n✓ \"file/with/slashes.png\" → \"file_with_slashes.png\"\n✓ \".hidden\" → \"_hidden\"\n✓ \"file with spaces.jpg\" → \"file_with_spaces.jpg\"\n```\n\n### Integration Test\n```bash\n✓ Real image generation with HTTPS URL: Success\n✓ HTTP URL rejection: Blocked as expected\n✓ Request timeout: All requests complete within 30s\n```\n\n---\n\n## Reporting Security Issues\n\nIf you discover a security vulnerability in this skill:\n\n1. **Do NOT open a public issue**\n2. Contact the skill maintainer directly\n3. Provide details: affected code, reproduction steps, potential impact\n4. Allow reasonable time for a fix before public disclosure\n\n---\n\n## Version History\n\n**v1.1.0** (2026-02-23)\n- Added URL validation (HTTPS-only, SSRF prevention)\n- Added request timeouts (30s default)\n- Added rate limiting for batch processing\n- Added filename sanitization\n\n**v1.0.0** (2026-02-22)\n- Initial release\n\n---\n\n**Security is a shared responsibility.** Keep your API keys secure, monitor usage, and report issues promptly.\n\nFile v1.0.1:SETUP-GUIDE.md\n\n# ProductAI Integration Setup Guide\n\n**Goal:** Make getting your ProductAI API key and integrating it with OpenClaw as easy as possible.\n\n## For End Users: Getting Started\n\n### Step 1: Get Your ProductAI API Key\n\n**Option A: If you already have a ProductAI account**\n\n1. Go to **[https://www.productai.photo](https://www.productai.photo)**\n2. Log in to your account\n3. Navigate to **API Access** (in the dashboard/settings)\n4. You'll see your API key displayed — copy it\n5. If no key exists, click **Generate API Key**\n\n**Option B: If you're new to ProductAI**\n\n1. Go to **[https://www.productai.photo](https://www.productai.photo)**\n2. Sign up for an account\n3. Choose a plan (Basic, Standard, or Pro)\n4. Once logged in, go to **API Access**\n5. Generate your first API key\n\n**⚠️ Important:** Keep your API key secret! Don't share it publicly or commit it to version control.\n\n### Step 2: Run the Setup Script\n\nOpen your terminal and run:\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nThe script will ask you a few questions:\n\n**Q: API Key:**\nPaste the key you copied from ProductAI Studio.\n\n**Q: API Endpoint:**\nJust press Enter (uses default: `https://api.productai.photo/v1`)\n\n**Q: Default Model:**\nPress Enter (uses `nanobanana` — good balance of speed and quality)\n\n**Q: Default Resolution:**\nPress Enter (uses `1024x1024`)\n\n**Q: Your Plan:**\nEnter `basic`, `standard`, or `pro` depending on your ProductAI subscription.\n\n**That's it!** Your configuration is saved and secured.\n\n### Step 3: Test It\n\nRun a quick test to make sure everything works:\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/test-product.jpg\" \\\n  --prompt \"white background\" \\\n  --output test.png\n```\n\nIf you see:\n```\n✓ Job created: 12345\n  Status: RUNNING\n\nWaiting for completion...\n\n✓ Generation complete!\nImage URL: https://...\nDownloading image to test.png...\n✓ Saved to test.png\n```\n\n**You're all set!** 🎉\n\n---\n\n## For Skill Creators: Integration Checklist\n\nWhen building a ProductAI integration for OpenClaw users, here's what to prepare:\n\n### Pre-Integration Questions to Ask\n\n**1. Account Status**\n- Do you have a ProductAI account? (Yes / No)\n- If yes, which plan? (Basic / Standard / Pro)\n\n**2. API Access**\n- Have you generated an API key? (Yes / No)\n- If yes, do you have it handy?\n\n**3. Use Case**\n- What will you use ProductAI for?\n  - E-commerce product photos?\n  - Marketing campaigns?\n  - Social media content?\n  - Other?\n\n### Setup Flow\n\n**Path A: User has API key already**\n```\n1. Run setup script\n2. Paste API key\n3. Test with sample generation\n4. Done!\n```\n\n**Path B: User needs to get API key**\n```\n1. Direct to productai.photo\n2. Guide through signup/login\n3. Navigate to API Access\n4. Copy key\n5. Run setup script\n6. Paste key\n7. Test\n8. Done!\n```\n\n### Making It \"Super Easy\"\n\n**✅ DO:**\n- Provide direct links to API Access page\n- Show screenshots of where to find the key\n- Auto-detect common issues (missing config, invalid key)\n- Test API key immediately after setup\n- Give clear success/failure messages\n- Provide example commands users can copy-paste\n\n**❌ DON'T:**\n- Ask for information you can auto-detect (endpoint URL, default model)\n- Require manual JSON editing\n- Show raw error messages without explanation\n- Leave users wondering if setup worked\n\n### Sample Setup Conversation Flow\n\n```\nAgent: \"Hey! To use ProductAI, I'll need your API key. Do you have one?\"\n\nUser: \"No\"\n\nAgent: \"No problem! Here's how to get one:\n\n1. Visit https://www.productai.photo\n2. Sign up or log in\n3. Go to API Access\n4. Copy your API key\n\nLet me know when you have it!\"\n\nUser: \"Got it: sk_prod_abc123...\"\n\nAgent: \"Perfect! Setting that up now...\"\n[Runs setup script programmatically]\n\nAgent: \"✓ API key saved and tested! Want to try generating an image?\"\n\nUser: \"Sure\"\n\nAgent: \"Great! Send me a product image URL and tell me what background you want.\"\n\nUser: \"https://example.com/watch.jpg — modern office desk\"\n\nAgent: [Runs generate_photo.py]\n\"Here's your result! [image]\"\n```\n\n### Error Handling\n\n**Invalid API Key (401)**\n```\nAgent: \"Hmm, that API key didn't work. Double-check it in ProductAI Studio → API Access. \nWant to try again or regenerate a new key?\"\n```\n\n**Out of Tokens**\n```\nAgent: \"Looks like you're out of tokens. You can:\n- Purchase more tokens at productai.photo\n- Upgrade your plan for more monthly credits\n\nLet me know when you're ready to try again!\"\n```\n\n**Rate Limited (429)**\n```\nAgent: \"ProductAI has a rate limit of 15 requests/minute. Let's wait a bit before trying again.\"\n[Auto-retry after delay]\n```\n\n---\n\n## Technical Implementation Notes\n\n### Config File Structure\n\n```json\n{\n  \"api_key\": \"sk_prod_...\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\n- Stored at: `~/.openclaw/workspace/productai/config.json`\n- Permissions: `600` (user read/write only)\n- Never log or display the API key\n\n### Testing the API Key\n\nAfter setup, immediately test with a simple API call:\n\n```python\nimport requests\n\nresponse = requests.get(\n    \"https://api.productai.photo/v1/api/job/1\",  # Dummy job ID\n    headers={\"x-api-key\": api_key}\n)\n\nif response.status_code == 401:\n    print(\"❌ Invalid API key\")\nelif response.status_code in [200, 404]:\n    print(\"✓ API key valid!\")\nelse:\n    print(f\"⚠️ Unexpected response: {response.status_code}\")\n```\n\n### Programmatic Setup (For Agents)\n\nAgents can run setup programmatically instead of interactively:\n\n```python\nimport json\nfrom pathlib import Path\n\nconfig = {\n    \"api_key\": user_provided_key,\n    \"api_endpoint\": \"https://api.productai.photo/v1\",\n    \"default_model\": \"nanobanana\",\n    \"default_resolution\": \"1024x1024\",\n    \"plan\": user_plan or \"standard\"\n}\n\nconfig_path = Path.home() / '.openclaw' / 'workspace' / 'productai' / 'config.json'\nconfig_path.parent.mkdir(parents=True, exist_ok=True)\n\nwith open(config_path, 'w') as f:\n    json.dump(config, f, indent=2)\n\nconfig_path.chmod(0o600)\n```\n\n---\n\n## FAQ\n\n**Q: Do I need to install anything?**\nA: Python dependencies are auto-installed. Just run the setup script.\n\n**Q: Can I change my API key later?**\nA: Yes! Just run `./scripts/setup.py` again and it will overwrite the old config.\n\n**Q: Where is my API key stored?**\nA: In `~/.openclaw/workspace/productai/config.json` (secured with 600 permissions).\n\n**Q: Can I use this with multiple ProductAI accounts?**\nA: You can only have one API key configured at a time. To switch accounts, run setup again.\n\n**Q: What if I run out of tokens?**\nA: Visit ProductAI Studio to purchase more or upgrade your plan.\n\n**Q: How do I know how many tokens I have left?**\nA: Check your ProductAI Studio dashboard for current balance.\n\n---\n\n**Questions or issues?** Check [SKILL.md](SKILL.md) or [API.md](references/API.md) for more details.\n\nFile v1.0.1:skill-card.md\n\n## Description:\n\nGenerates professional AI product photos with ProductAI.photo for e-commerce, marketing, catalogs, and campaigns, including background replacement, product placement, scene generation, compositing, and upscaling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[shapes-2](https://clawhub.ai/user/shapes-2)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nExternal users, developers, marketers, and e-commerce teams use this skill to configure ProductAI access, generate product photos from image URLs, create lifestyle or catalog visuals, upscale images, and run batch generation workflows.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles long-lived ProductAI API keys.\n\nMitigation: Use the official ProductAI endpoint, avoid sharing API keys in ordinary chat or logs, store credentials with user-only permissions, and rotate any key that may have been exposed.\n\nRisk: Product images and generated outputs are sent to and downloaded from a third-party service.\n\nMitigation: Submit only images that are appropriate for ProductAI's handling terms, avoid confidential or rights-restricted material unless approved, and treat downloaded image results as untrusted remote content.\n\nRisk: Generation and upscaling consume ProductAI tokens and can create unexpected cost if used carelessly.\n\nMitigation: Monitor ProductAI token usage, respect the documented rate limits, and use batch workflows deliberately.\n\n## Reference(s):\n\n- [ProductAI Website](https://www.productai.photo)\n- [ProductAI API Reference](references/API.md)\n- [ProductAI Integration Guide](references/INTEGRATION_GUIDE.md)\n- [Quick Start Guide](QUICKSTART.md)\n- [Setup Guide](SETUP-GUIDE.md)\n- [ClawHub Skill Page](https://clawhub.ai/shapes-2/skills/productai-skill)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration, API calls, Files]\n\n**Output Format:** [Markdown guidance with shell commands, JSON configuration, API requests, and generated or upscaled image files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses ProductAI API jobs, may print job IDs or result URLs, and can download generated images to local output paths.]\n\n## Skill Version(s):\n\n1.0.1 (source: server release metadata; artifact package.json and CHANGELOG list 1.2.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.1:config.example.json\n\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n\nArchive v1.0.0: 16 files, 36025 bytes\n\nFiles: config.example.json (181b), INTEGRATION-QUESTIONS.md (6069b), package.json (1013b), QUICKSTART.md (4539b), README.md (4097b), references/API.md (7763b), references/INTEGRATION_GUIDE.md (15542b), scripts/batch_generate.py (7864b), scripts/generate_photo.py (6855b), scripts/productai_client.py (9513b), scripts/setup.py (2756b), scripts/upscale_image.py (4359b), SECURITY.md (6367b), SETUP-GUIDE.md (6870b), SKILL.md (7203b), _meta.json (134b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: productai\ndescription: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, marketing, catalogs, or campaigns. Supports background replacement, product placement, scene generation, adaptive templates, and video ads. Use for tasks involving product photography, lifestyle shots, mockups, or marketing visuals.\n---\n\n# ProductAI Integration\n\nProductAI.photo is an AI-powered service that generates professional product photos from existing images. It enables e-commerce businesses, marketers, and designers to create studio-quality product photography without hiring photographers.\n\n## Quick Start\n\n**1. Get Your API Key**\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your API key\n\n**2. Run Setup**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n# Paste your API key when prompted\n```\n\n**3. Generate Images**\n\n```bash\n# Generate product photo with custom background\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"modern living room with natural lighting\" \\\n  --output result.png\n\n# Use multiple reference images (nanobanana/seedream support 2 images)\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Put the first image on top of the second image\" \\\n  --output result.png\n\n# High quality with Nano Banana Pro\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"white studio background\" \\\n  --model nanobananapro \\\n  --output hq.png\n\n# Upscale an image (20 tokens)\nscripts/upscale_image.py \\\n  --image https://example.com/photo.jpg \\\n  --output upscaled.png\n```\n\n## Core Capabilities\n\n**Photo Generation (`/api/generate`)**\n- Background replacement with AI-generated scenes\n- Product placement in realistic environments\n- Multi-image compositing (up to 2 reference images with certain models)\n- Custom prompts for full creative control\n\n**Image Upscaling (`/api/upscale`)**\n- Professional AI upscaling (Magnific Precision Upscale)\n- Preserves image details without distortion\n- 20 tokens per upscale\n\n**Models Available**\n- **gpt-low** — GPT Low Quality (2 tokens)\n- **gpt-medium** — GPT Medium Quality (3 tokens)\n- **gpt-high** — GPT High Quality (8 tokens)\n- **kontext-pro** — Kontext Pro (3 tokens)\n- **nanobanana** — Nano Banana (3 tokens) — **DEFAULT**\n- **nanobananapro** — Nano Banana Pro (8 tokens)\n- **seedream** — Seedream (3 tokens)\n\n**Multi-Image Support:**\n`nanobanana`, `nanobananapro`, and `seedream` support up to 2 reference images for advanced compositing.\n\n## Configuration\n\n### API Setup\n\n**Step 1: Get Your API Key**\n\n1. Visit [ProductAI Studio](https://www.productai.photo)\n2. Navigate to **API Access** section\n3. Click **Generate API Key** or copy existing key\n\n**Step 2: Run Setup Script**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n```\n\nThis will interactively create `config.json` with your credentials:\n\n```json\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\nThe config file is automatically secured with 600 permissions.\n\n### Installation\n\nThe integration scripts require Python 3.7+ with these dependencies:\n\n```bash\npip install requests pillow\n```\n\nAll dependencies are handled automatically by the scripts.\n\n## Usage Examples\n\n### E-commerce Product Photos\n\nGenerate clean product shots for online stores:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/raw-product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output store-listing.png\n```\n\n### Marketing Campaign Visuals\n\nCreate lifestyle shots for advertising:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/bottle.jpg \\\n  --prompt \"outdoor picnic scene with blanket and basket, golden hour lighting\" \\\n  --output campaign-hero.png \\\n  --model kontext-pro\n```\n\n### Multi-Image Compositing\n\nCombine multiple products into one scene:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Place the lipstick on top of the cosmetics box\" \\\n  --model nanobanana \\\n  --output composite.png\n```\n\n### High-Quality Output\n\nUse Nano Banana Pro for premium results:\n\n```bash\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"luxury marble countertop setting with morning light\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n### Image Upscaling\n\nUpscale images for print or high-res displays:\n\n```bash\nscripts/upscale_image.py \\\n  --image https://example.com/product.jpg \\\n  --output upscaled.png\n```\n\n### Async Workflow (No Wait)\n\nStart generation and check later:\n\n```bash\n# Start job (prints job ID)\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"studio background\" \\\n  --no-wait\n\n# Output: Job created: 12345\n\n# Later, resume and download\nscripts/generate_photo.py \\\n  --job-id 12345 \\\n  --output result.png\n```\n\n## API Reference\n\nSee [API.md](references/API.md) for complete endpoint documentation, request/response formats, and authentication details.\n\n## Pricing & Token Costs\n\nProductAI uses a token-based pricing system:\n\n| Operation | Token Cost |\n|-----------|------------|\n| GPT Low Quality Generation | 2 tokens |\n| GPT Medium Quality Generation | 3 tokens |\n| GPT High Quality Generation | 8 tokens |\n| Kontext Pro | 3 tokens |\n| Nano Banana Pro | 8 tokens |\n| Nano Banana | 3 tokens |\n| Seedream | 3 tokens |\n| Magnific Precision Upscale | 20 tokens |\n\n**Subscription Plans:**\n\nVisit [ProductAI.photo](https://www.productai.photo) for current plans and token packages.\n\n**Rate Limits:**\n- 15 requests per minute\n- Daily limits based on subscription plan\n\n**Note:** Tokens are deducted when each operation **starts** (not on completion).\n\n## Troubleshooting\n\n**API Key Issues**\n- Verify `config.json` exists: `cat ~/.openclaw/workspace/productai/config.json`\n- Check API key in ProductAI Studio → API Access\n- Regenerate key if needed\n\n**OUT_OF_TOKENS Error**\n- Check your token balance in ProductAI Studio\n- Purchase more tokens or upgrade plan\n- Remember: tokens are deducted when jobs **start**, not on completion\n\n**Rate Limit (429)**\n- Maximum 15 requests per minute\n- Wait before retrying\n- Use `--no-wait` for batch jobs and check status later\n\n**Job Failed (ERROR status)**\n- Check image URL is accessible and under 10MB\n- Verify image format (PNG, JPG, or WebP only)\n- Check prompt length and content\n- Try a different model\n\n**Multi-Image Not Working**\n- Only `nanobanana`, `nanobananapro`, and `seedream` support multiple images\n- Maximum 2 reference images\n- Use array format: `--image url1 url2`\n\n## Support\n\n- Website: https://www.productai.photo\n- Documentation: See references/API.md\n- Contact: support@productai.photo (or team contact when available)\n\n## Advanced Topics\n\nFor detailed API specifications, authentication flows, webhook integration, and batch processing patterns, see [API.md](references/API.md).\n\nFile v1.0.0:README.md\n\n# ProductAI Integration for OpenClaw\n\nGenerate professional AI product photos directly from OpenClaw using the ProductAI.photo API.\n\n## What is ProductAI?\n\nProductAI.photo is an AI-powered service that transforms product images with:\n- Background replacement and scene generation\n- Multi-image compositing\n- Professional upscaling\n- Multiple AI models for different quality levels\n\nPerfect for e-commerce, marketing, and content creation.\n\n## Quick Links\n\n- **[ProductAI Website](https://www.productai.photo)** — Sign up & get API key\n- **[Quick Start Guide](QUICKSTART.md)** — Get running in 5 minutes\n- **[Setup Guide](SETUP-GUIDE.md)** — Detailed setup instructions & FAQ\n- **[Skill Documentation](SKILL.md)** — Full feature reference\n- **[API Reference](references/API.md)** — Complete API documentation\n\n## Installation\n\n### 1. Get Your API Key\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your key\n\n### 2. Run Setup\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nPaste your API key when prompted. That's it!\n\n### 3. Generate Images\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"white studio background\" \\\n  --output result.png\n```\n\n## Available Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `setup.py` | Configure API credentials |\n| `generate_photo.py` | Generate product photos |\n| `upscale_image.py` | Upscale images (20 tokens) |\n| `batch_generate.py` | Batch process multiple images |\n\n## Common Use Cases\n\n### Clean Product Backgrounds\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/messy.jpg\" \\\n  --prompt \"pure white background\" \\\n  --output clean.png\n```\n\n### Lifestyle Photography\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/watch.jpg\" \\\n  --prompt \"wrist wearing watch, business setting\" \\\n  --output lifestyle.png\n```\n\n### Multi-Image Compositing\n```bash\n./scripts/generate_photo.py \\\n  --image \"url1\" \"url2\" \\\n  --prompt \"Combine both products\" \\\n  --model nanobanana \\\n  --output combo.png\n```\n\n### High Quality (Nano Banana Pro)\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"luxury marble countertop\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n## Models & Pricing\n\n| Model | Cost | Quality |\n|-------|------|---------|\n| `gpt-low` | 2 tokens | Low |\n| `gpt-medium` | 3 tokens | Medium |\n| `nanobanana` | 3 tokens | **Recommended** |\n| `kontext-pro` | 3 tokens | Good |\n| `seedream` | 3 tokens | Creative |\n| `gpt-high` | 8 tokens | High |\n| `nanobananapro` | 8 tokens | Premium |\n| **Upscale** | 20 tokens | — |\n\n**Multi-image support:** `nanobanana`, `nanobananapro`, `seedream` (max 2 images)\n\n## Documentation\n\n- **New users:** Start with [QUICKSTART.md](QUICKSTART.md)\n- **Setup help:** See [SETUP-GUIDE.md](SETUP-GUIDE.md)\n- **Feature reference:** Read [SKILL.md](SKILL.md)\n- **API details:** Check [API.md](references/API.md)\n- **Security:** See [SECURITY.md](SECURITY.md)\n\n## Troubleshooting\n\n**\"Config file not found\"**\n→ Run `./scripts/setup.py` first\n\n**\"OUT_OF_TOKENS\"**\n→ Purchase more tokens at [productai.photo](https://www.productai.photo)\n\n**\"Unauthorized\" (401)**\n→ Check your API key in ProductAI Studio → API Access\n\n**Rate limited (429)**\n→ Wait a minute (limit: 15 requests/minute)\n\nMore help in [SETUP-GUIDE.md](SETUP-GUIDE.md#troubleshooting)\n\n## Security Features\n\n✅ **HTTPS-only URLs** — Blocks HTTP to prevent insecure requests  \n✅ **SSRF Prevention** — Blocks private IPs and localhost  \n✅ **Request Timeouts** — All HTTP requests timeout after 30s  \n✅ **Rate Limiting** — Batch processing respects 15 req/min limit  \n✅ **Path Traversal Protection** — Sanitizes all filenames\n\nSee [SECURITY.md](SECURITY.md) for full details.\n\n## Support\n\n- **Website:** https://www.productai.photo\n- **Get API Key:** ProductAI Studio → API Access\n- **Issues:** Contact ProductAI support via dashboard\n\n---\n\n**Ready to create amazing product photos?** Start with [QUICKSTART.md](QUICKSTART.md)!\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn747nct6wegm6yhndknwfj27s81q02v\",\n  \"slug\": \"productai-skill\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1771854826119\n}\n\nFile v1.0.0:references/API.md\n\n# ProductAI API Documentation\n\nComplete reference for the ProductAI.photo API endpoints.\n\n## Base URL\n\n```\nhttps://api.productai.photo/v1\n```\n\nAll API requests should be made to this base URL with the appropriate endpoint path.\n\n## Authentication\n\nInclude your API key in the `x-api-key` header for all requests:\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/generate \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"kontext-pro\", \"image_url\": \"https://example.com/product.jpg\", \"prompt\": \"Add sunglasses\"}'\n```\n\n**Getting Your API Key:**\n\n1. Go to [ProductAI Studio](https://www.productai.photo)\n2. Navigate to **API Access** section\n3. Click **Generate API Key** or copy existing key\n4. Store securely in your configuration\n\n## Rate Limits\n\n- **Rate Limit:** 15 requests per minute\n- **Daily Limit:** Based on your subscription plan\n- **Credit System:** Each operation deducts tokens from your account balance\n\n## Endpoints\n\n### POST `/api/generate`\n\nGenerate AI-powered product images using the ProductAI engine.\n\n**Request Body:**\n\n```json\n{\n  \"model\": \"kontext-pro\",\n  \"image_url\": \"https://example.com/product.jpg\",\n  \"prompt\": \"Add sunglasses\"\n}\n```\n\n**Parameters:**\n\n- **`model`** (required) — Model to use for generation:\n  - `gpt-low` — GPT Low Quality Generation (2 tokens)\n  - `gpt-medium` — GPT Medium Quality Generation (3 tokens)\n  - `gpt-high` — GPT High Quality Generation (8 tokens)\n  - `kontext-pro` — Kontext Pro (3 tokens)\n  - `nanobanana` — Nano Banana (3 tokens)\n  - `nanobananapro` — Nano Banana Pro (8 tokens)\n  - `seedream` — Seedream (3 tokens)\n\n- **`image_url`** (required) — URL of the source image to process\n  - Can be a single URL string OR array of URLs\n  - **`seedream`, `nanobananapro`, and `nanobanana` models support up to 2 reference images (use array format!)**\n  - Each image must be below 10MB in PNG, JPG, or WebP format\n\n- **`prompt`** (required) — Text description of desired output\n\n**Success Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"RUNNING\",\n    \"prompt\": \"lipstick should be on fire\"\n  }\n}\n```\n\n**Running Job Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"RUNNING\",\n    \"prompt\": \"lipstick should be on fire\"\n  }\n}\n```\n\n**Completed Job Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"COMPLETED\",\n    \"prompt\": \"lipstick should be on fire\",\n    \"image_url\": \"https://generated-image-url.jpg\"\n  }\n}\n```\n\n**Status Values:**\n- `\"RUNNING\"` — Job is currently being processed\n- `\"COMPLETED\"` — Job completed successfully, image_url available\n- `\"ERROR\"` — Job failed to complete\n\n**Error Response (Out of Credits):**\n\n```json\n{\n  \"name\": \"ApiError\",\n  \"message\": \"OUT_OF_TOKENS\",\n  \"details\": \"Not enough credits\"\n}\n```\n\n---\n\n### POST `/api/upscale`\n\nUpscale an image using professional AI upscaling technology without changing image details.\n\n**Request Body:**\n\n```json\n{\n  \"image_url\": \"https://example.com/image.jpg\"\n}\n```\n\n**Parameters:**\n\n- **`image_url`** (required) — URL of the image to upscale\n  - Image must be below 10MB in PNG, JPG, or WebP format\n\n**Token Cost:** 20 tokens (Magnific Precision Upscale)\n\n**Success Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22293,\n    \"status\": \"RUNNING\"\n  }\n}\n```\n\n**Completed Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22293,\n    \"status\": \"COMPLETED\",\n    \"image_url\": \"https://upscaled-image-url.jpg\"\n  }\n}\n```\n\n**Error Response:**\n\n```json\n{\n  \"name\": \"ApiError\",\n  \"message\": \"OUT_OF_TOKENS\",\n  \"details\": \"Not enough credits\"\n}\n```\n\n---\n\n### GET `/api/job/:job_id`\n\nCheck the status of a specific generation job using the job ID returned from `/api/generate` or `/api/upscale`.\n\n**URL Parameters:**\n\n- **`job_id`** (required) — The job ID returned from generate/upscale request\n\n**Example Request:**\n\n```bash\ncurl -X GET https://api.productai.photo/v1/api/job/22292 \\\n  -H \"x-api-key: YOUR_API_KEY\"\n```\n\n**Success Response (Completed):**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"COMPLETED\",\n    \"prompt\": \"lipstick should be on fire\",\n    \"image_url\": \"https://generated-image-url.jpg\"\n  }\n}\n```\n\n**Running Job Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"RUNNING\",\n    \"prompt\": \"lipstick should be on fire\"\n  }\n}\n```\n\n**Error Response:**\n\n```json\n{\n  \"status\": \"OK\",\n  \"data\": {\n    \"id\": 22292,\n    \"status\": \"ERROR\"\n  }\n}\n```\n\n---\n\n## Webhooks\n\nFor each image generation request, a result will be sent to your configured webhook URL.\n\n**Configure Webhook:**\n\nSet your webhook URL in the **API Access** page in the ProductAI Studio.\n\n**Webhook Payload (Success):**\n\n```json\n{\n  \"status\": \"success\",\n  \"image_url\": \"https://generated-image-url.jpg\",\n  \"job_id\": \"12312\"\n}\n```\n\n**Webhook Payload (Error):**\n\n```json\n{\n  \"status\": \"error\"\n}\n```\n\n**Webhook Requirements:**\n\n- Your endpoint must respond with HTTP 200 status\n- Configure your webhook URL in the API Access page\n- Webhook calls are sent when jobs complete (success or error)\n\n---\n\n## Token Pricing\n\n| Operation | Token Cost |\n|-----------|------------|\n| GPT Low Quality Generation | 2 tokens |\n| GPT Medium Quality Generation | 3 tokens |\n| GPT High Quality Generation | 8 tokens |\n| Kontext Pro | 3 tokens |\n| Nano Banana Pro | 8 tokens |\n| Nano Banana | 3 tokens |\n| Seedream | 3 tokens |\n| Magnific Precision Upscale | 20 tokens |\n\n**Note:** Tokens are deducted from your account balance when each operation starts.\n\n---\n\n## Common Error Codes\n\n| Code | Message | Description |\n|------|---------|-------------|\n| 400 | Bad Request | Invalid parameters |\n| 401 | Unauthorized | Invalid API key |\n| 500 | Internal Server Error | Server-side error |\n| — | OUT_OF_TOKENS | Not enough credits |\n\n---\n\n## Usage Examples\n\n### Generate Product Photo with Multiple Reference Images\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/generate \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"nanobanana\",\n    \"image_url\": [\n      \"https://example.com/product1.jpg\",\n      \"https://example.com/product2.jpg\"\n    ],\n    \"prompt\": \"Put the first image on top of the second image.\"\n  }'\n```\n\n### Poll Job Status Until Complete\n\n```bash\n#!/bin/bash\nAPI_KEY=\"YOUR_API_KEY\"\nJOB_ID=\"22292\"\n\nwhile true; do\n  RESPONSE=$(curl -s -X GET \\\n    \"https://api.productai.photo/v1/api/job/$JOB_ID\" \\\n    -H \"x-api-key: $API_KEY\")\n  \n  STATUS=$(echo \"$RESPONSE\" | jq -r '.data.status')\n  \n  if [ \"$STATUS\" == \"COMPLETED\" ]; then\n    IMAGE_URL=$(echo \"$RESPONSE\" | jq -r '.data.image_url')\n    echo \"Done! Image URL: $IMAGE_URL\"\n    break\n  elif [ \"$STATUS\" == \"ERROR\" ]; then\n    echo \"Job failed\"\n    break\n  else\n    echo \"Still running... ($STATUS)\"\n    sleep 5\n  fi\ndone\n```\n\n### Upscale an Image\n\n```bash\ncurl -X POST https://api.productai.photo/v1/api/upscale \\\n  -H \"x-api-key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image_url\": \"https://example.com/image.jpg\"\n  }'\n```\n\n---\n\n## Best Practices\n\n1. **Poll Responsibly:** Wait at least 3-5 seconds between job status checks\n2. **Handle Rate Limits:** Implement exponential backoff for 429 responses\n3. **Use Webhooks:** For production, configure webhooks instead of polling\n4. **Validate Images:** Ensure images are under 10MB and in supported formats\n5. **Monitor Credits:** Check account balance regularly to avoid OUT_OF_TOKENS errors\n6. **Secure API Keys:** Never commit API keys to version control\n\n---\n\n## Support\n\n- **Website:** https://www.productai.photo\n- **API Issues:** Contact support via the dashboard\n- **Rate Limit Increases:** Available for Pro plan users\n\nFile v1.0.0:references/INTEGRATION_GUIDE.md\n\n# ProductAI Integration Guide\n\nComplete guide for integrating ProductAI into your applications, workflows, and AI agents.\n\n## Quick Start (5 minutes)\n\n### 1. Install the Skill\n\n```bash\n# If skill is packaged as .skill file\nopenclaw skills install productai.skill\n\n# Or clone directly\ngit clone https://github.com/your-org/productai-skill ~/.openclaw/workspace/productai\n```\n\n### 2. Configure API Credentials\n\n```bash\ncd ~/.openclaw/workspace/productai\npython3 scripts/setup.py\n```\n\nOr manually create `config.json`:\n\n```json\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nano-banana-2\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\n### 3. Test It\n\n```bash\n# Generate your first photo\nscripts/generate_photo.py \\\n  --image product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output result.png\n```\n\n**Done!** You now have ProductAI integrated.\n\n## Integration Patterns\n\n### Pattern 1: Command-Line Scripts\n\nBest for: Manual workflows, batch jobs, cron tasks\n\n```bash\n# Single photo generation\nscripts/generate_photo.py --image product.jpg --prompt \"modern living room\" --output result.png\n\n# Background replacement\nscripts/generate_photo.py --image product.jpg --background-replace --output clean.png\n\n# Batch processing\nscripts/batch_generate.py \\\n  --input-dir ./products \\\n  --output-dir ./processed \\\n  --template \"white background with subtle shadows\"\n```\n\n### Pattern 2: Python Library\n\nBest for: Python applications, Jupyter notebooks, automation scripts\n\n```python\nfrom productai_client import create_client\n\n# Initialize client\nclient = create_client()\n\n# Generate photo\nresult = client.generate(\n    image='product.jpg',\n    prompt='modern living room with natural lighting'\n)\n\n# Download result\nclient.download_result(result['image_url'], 'output.png')\n\nprint(f\"Credits used: {result['credits_used']}\")\nprint(f\"Processing time: {result['processing_time_ms']}ms\")\n```\n\n### Pattern 3: AI Agent Integration\n\nBest for: OpenClaw agents, LangChain, AutoGPT, other AI systems\n\n**OpenClaw Integration:**\n\nThe skill is auto-loaded when OpenClaw detects product photo tasks. Just ask:\n\n> \"Generate a professional product photo of this bottle in a modern kitchen setting\"\n\n**Custom Agent Integration:**\n\n```python\nimport subprocess\nimport json\n\ndef generate_product_photo(image_path: str, prompt: str) -> dict:\n    \"\"\"Call ProductAI from any AI agent.\"\"\"\n    result = subprocess.run(\n        [\n            'python3',\n            '/path/to/productai/scripts/generate_photo.py',\n            '--image', image_path,\n            '--prompt', prompt,\n            '--output', 'result.png'\n        ],\n        capture_output=True,\n        text=True\n    )\n    \n    return json.loads(result.stdout)\n\n# Use in your agent\nresult = generate_product_photo('product.jpg', 'white background')\nprint(f\"Generated: {result['image_url']}\")\n```\n\n### Pattern 4: REST API Wrapper\n\nBest for: Microservices, web apps, team access\n\n```python\nfrom flask import Flask, request, jsonify\nfrom productai_client import create_client\n\napp = Flask(__name__)\nclient = create_client()\n\n@app.route('/api/generate', methods=['POST'])\ndef generate():\n    data = request.json\n    \n    result = client.generate(\n        image=data['image'],\n        prompt=data['prompt'],\n        model=data.get('model', 'nano-banana-2')\n    )\n    \n    return jsonify(result)\n\n@app.route('/api/background-replace', methods=['POST'])\ndef background_replace():\n    data = request.json\n    \n    result = client.background_replace(\n        image=data['image'],\n        background_type=data.get('background_type', 'white')\n    )\n    \n    return jsonify(result)\n\nif __name__ == '__main__':\n    app.run(port=5000)\n```\n\n## Real-World Use Cases\n\n### E-Commerce Product Photos\n\n**Challenge:** Need 1000 product photos with consistent white backgrounds for Shopify store.\n\n**Solution:**\n\n```bash\n# 1. Organize products\nmkdir -p products/raw products/processed\n\n# 2. Batch process with white background\nscripts/batch_generate.py \\\n  --input-dir products/raw \\\n  --output-dir products/processed \\\n  --template \"clean white background with soft drop shadow\" \\\n  --max-workers 5\n\n# 3. Upload to Shopify (use Shopify API or bulk upload)\n```\n\n**Result:** Professional product photos at 10x lower cost than photographer.\n\n### Marketing Campaign Visuals\n\n**Challenge:** Create lifestyle product shots for Instagram campaign.\n\n**Solution:**\n\n```python\nfrom productai_client import create_client\n\nclient = create_client()\n\nscenes = [\n    \"product on rustic wooden table with morning coffee\",\n    \"product held in hands outdoors with natural lighting\",\n    \"product on modern desk with laptop and plant\",\n    \"product on kitchen counter with fresh ingredients\"\n]\n\nfor i, scene in enumerate(scenes):\n    result = client.generate(\n        image='product.jpg',\n        prompt=scene,\n        model='flux-kontext',\n        resolution='1024x1024'\n    )\n    \n    client.download_result(\n        result['image_url'],\n        f'campaign/instagram_{i+1}.png'\n    )\n    \n    print(f\"✓ Generated scene {i+1}: {scene}\")\n```\n\n**Result:** 4 unique lifestyle shots ready for social media in minutes.\n\n### Product Catalog Updates\n\n**Challenge:** Seasonal catalog needs all products re-shot with holiday theme.\n\n**Solution:**\n\n```bash\n# Generate holiday-themed versions\nscripts/batch_generate.py \\\n  --input-dir catalog/products \\\n  --output-dir catalog/holiday \\\n  --template \"festive holiday setting with warm lighting and decorations\" \\\n  --model nano-banana-2-pro\n\n# Or summer theme\nscripts/batch_generate.py \\\n  --input-dir catalog/products \\\n  --output-dir catalog/summer \\\n  --template \"bright summer outdoor setting with natural sunlight\"\n```\n\n**Result:** Entire catalog refreshed for new season without re-shooting products.\n\n### Automated Listing Generator\n\n**Challenge:** Automatically create marketplace listings with professional photos.\n\n**Solution:**\n\n```python\nfrom productai_client import create_client\nimport csv\n\nclient = create_client()\n\n# Read product inventory\nwith open('inventory.csv') as f:\n    products = csv.DictReader(f)\n    \n    for product in products:\n        # Generate professional photo\n        result = client.generate(\n            image=product['raw_photo_url'],\n            prompt='clean white background for e-commerce',\n            model='nano-banana-2'\n        )\n        \n        # Download and save\n        output_path = f\"listings/{product['sku']}.png\"\n        client.download_result(result['image_url'], output_path)\n        \n        # Create listing (pseudo-code)\n        create_marketplace_listing(\n            title=product['name'],\n            image=output_path,\n            price=product['price']\n        )\n        \n        print(f\"✓ Listed {product['name']}\")\n```\n\n**Result:** Fully automated listing creation with professional photos.\n\n## Advanced Topics\n\n### Custom Webhooks\n\nGet notified when batch jobs complete:\n\n```python\nfrom flask import Flask, request\nfrom productai_client import create_client\n\napp = Flask(__name__)\nclient = create_client()\n\n@app.route('/webhook/productai', methods=['POST'])\ndef productai_webhook():\n    event = request.json\n    \n    if event['event'] == 'job.completed':\n        job_id = event['job_id']\n        result_url = event['result']['image_url']\n        \n        # Process completed job\n        client.download_result(result_url, f'results/{job_id}.png')\n        \n        # Trigger next step in workflow\n        process_completed_image(job_id)\n    \n    return '', 200\n\n# Submit async batch\nresult = client.batch_generate(\n    images=['product1.jpg', 'product2.jpg'],\n    template='white background',\n    webhook_url='https://your-server.com/webhook/productai'\n)\n\nbatch_id = result['batch_id']\nprint(f\"Batch submitted: {batch_id}\")\n```\n\n### Credit Management\n\nMonitor and optimize credit usage:\n\n```python\nfrom productai_client import create_client\n\nclient = create_client()\n\n# Track credits\ntotal_credits = 0\nresults = []\n\nfor image in product_images:\n    result = client.generate(image=image, prompt='white background')\n    \n    credits_used = result['credits_used']\n    total_credits += credits_used\n    results.append(result)\n    \n    print(f\"Processed {image}: {credits_used} credits\")\n\nprint(f\"Total credits used: {total_credits}\")\nprint(f\"Average per image: {total_credits / len(product_images):.2f}\")\n```\n\n**Optimization tips:**\n- Use lower resolution for thumbnails\n- Batch similar products to save credits\n- Cache generated images\n- Use Basic plan for simple backgrounds, Pro for high-end\n\n### Quality Control\n\nImplement QA checks on generated images:\n\n```python\nfrom PIL import Image\nimport requests\nfrom productai_client import create_client\n\nclient = create_client()\n\ndef check_image_quality(image_url: str) -> dict:\n    \"\"\"Basic quality checks on generated image.\"\"\"\n    response = requests.get(image_url)\n    img = Image.open(BytesIO(response.content))\n    \n    width, height = img.size\n    aspect_ratio = width / height\n    \n    # Check resolution\n    if width < 1000 or height < 1000:\n        return {'status': 'low_resolution', 'width': width, 'height': height}\n    \n    # Check aspect ratio (for square products)\n    if not (0.9 < aspect_ratio < 1.1):\n        return {'status': 'wrong_aspect_ratio', 'ratio': aspect_ratio}\n    \n    return {'status': 'ok'}\n\n# Generate with QA\nresult = client.generate(\n    image='product.jpg',\n    prompt='white background',\n    resolution='1024x1024'\n)\n\nqa_result = check_image_quality(result['image_url'])\nif qa_result['status'] == 'ok':\n    client.download_result(result['image_url'], 'approved.png')\nelse:\n    print(f\"Quality issue: {qa_result}\")\n    # Retry or flag for manual review\n```\n\n### Template Management\n\nCreate reusable templates for consistent brand styling:\n\n```python\n# templates.py\nTEMPLATES = {\n    'ecommerce_white': 'clean white background with soft drop shadow',\n    'ecommerce_grey': 'light grey gradient background',\n    'lifestyle_home': 'modern home interior with natural lighting',\n    'lifestyle_outdoor': 'outdoor setting with natural environment',\n    'hands_holding': 'product held in hands with professional lighting',\n    'table_flat_lay': 'flat lay on white marble table with props'\n}\n\n# Use templates\nfrom productai_client import create_client\n\nclient = create_client()\n\nresult = client.generate(\n    image='product.jpg',\n    prompt=TEMPLATES['lifestyle_home'],\n    model='flux-kontext'\n)\n```\n\n### Error Handling & Retries\n\nRobust error handling for production:\n\n```python\nimport time\nfrom productai_client import create_client, ProductAIClient\nimport requests\n\ndef generate_with_retry(\n    client: ProductAIClient,\n    image: str,\n    prompt: str,\n    max_retries: int = 3\n) -> dict:\n    \"\"\"Generate with exponential backoff retry.\"\"\"\n    \n    for attempt in range(max_retries):\n        try:\n            result = client.generate(image=image, prompt=prompt)\n            return result\n            \n        except requests.exceptions.HTTPError as e:\n            if e.response.status_code == 429:\n                # Rate limited\n                wait = 2 ** attempt\n                print(f\"Rate limited. Waiting {wait}s...\")\n                time.sleep(wait)\n                continue\n            \n            elif e.response.status_code == 402:\n                # Insufficient credits\n                raise Exception(\"Out of credits\")\n            \n            elif attempt == max_retries - 1:\n                # Last attempt, give up\n                raise\n            \n            else:\n                # Other error, retry\n                wait = 2 ** attempt\n                time.sleep(wait)\n                continue\n        \n        except requests.exceptions.RequestException as e:\n            # Network error\n            if attempt == max_retries - 1:\n                raise\n            \n            wait = 2 ** attempt\n            print(f\"Network error. Retrying in {wait}s...\")\n            time.sleep(wait)\n            continue\n    \n    raise Exception(\"Max retries exceeded\")\n\n# Use it\nclient = create_client()\nresult = generate_with_retry(client, 'product.jpg', 'white background')\n```\n\n## Performance Optimization\n\n### Parallel Processing\n\n```python\nfrom concurrent.futures import ThreadPoolExecutor, as_completed\nfrom productai_client import create_client\n\nclient = create_client()\n\ndef process_product(image_path: str, template: str) -> dict:\n    result = client.generate(image=image_path, prompt=template)\n    return {'input': image_path, 'result': result}\n\n# Process 100 products in parallel (respect rate limits)\nwith ThreadPoolExecutor(max_workers=5) as executor:\n    futures = {\n        executor.submit(process_product, img, 'white background'): img\n        for img in product_images\n    }\n    \n    for future in as_completed(futures):\n        result = future.result()\n        print(f\"✓ Processed {result['input']}\")\n```\n\n### Caching Strategy\n\n```python\nimport hashlib\nimport json\nfrom pathlib import Path\n\nCACHE_DIR = Path('cache/productai')\nCACHE_DIR.mkdir(parents=True, exist_ok=True)\n\ndef get_cache_key(image: str, prompt: str, **kwargs) -> str:\n    \"\"\"Generate cache key from parameters.\"\"\"\n    params = {'image': image, 'prompt': prompt, **kwargs}\n    key_string = json.dumps(params, sort_keys=True)\n    return hashlib.md5(key_string.encode()).hexdigest()\n\ndef cached_generate(client, image: str, prompt: str, **kwargs) -> dict:\n    \"\"\"Generate with caching.\"\"\"\n    cache_key = get_cache_key(image, prompt, **kwargs)\n    cache_file = CACHE_DIR / f\"{cache_key}.json\"\n    \n    # Check cache\n    if cache_file.exists():\n        print(f\"Cache hit: {cache_key}\")\n        return json.loads(cache_file.read_text())\n    \n    # Generate\n    result = client.generate(image=image, prompt=prompt, **kwargs)\n    \n    # Cache result\n    cache_file.write_text(json.dumps(result, indent=2))\n    \n    return result\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Issue:** `Configuration file not found`\n\n**Solution:**\n```bash\ncd ~/.openclaw/workspace/productai\npython3 scripts/setup.py\n```\n\n---\n\n**Issue:** `API Error 401: Unauthorized`\n\n**Solution:** Check your API key in `config.json` is correct.\n\n---\n\n**Issue:** `API Error 402: Insufficient credits`\n\n**Solution:** Your plan has run out of credits. Upgrade or wait for monthly reset.\n\n---\n\n**Issue:** `API Error 429: Rate limit exceeded`\n\n**Solution:** Reduce `max_workers` in batch jobs or add delays between requests.\n\n---\n\n**Issue:** Generated images don't match prompt\n\n**Solution:** \n- Make prompts more specific\n- Try different models (flux-kontext for placement, nano-banana-2-pro for quality)\n- Adjust scale parameter\n\n---\n\n**Issue:** Batch processing too slow\n\n**Solution:**\n- Increase `max_workers` (respect rate limits)\n- Use async batch API with webhooks instead of polling\n- Parallelize with multiple API keys if allowed\n\n## Support & Resources\n\n- **Documentation:** `references/API.md`\n- **Website:** https://www.productai.photo\n- **Email:** support@productai.photo\n- **Discord:** (when available)\n\n## Contributing\n\nTo contribute improvements to this integration:\n\n1. Fork the skill repository\n2. Make your changes\n3. Test thoroughly\n4. Submit pull request with description\n\n**Areas for contribution:**\n- Additional language bindings (JS, Ruby, Go)\n- Enhanced error handling\n- Performance optimizations\n- New templates and presets\n- Integration examples\n\n## License\n\nThis integration skill is provided as-is for use with ProductAI service.\nCheck ProductAI's terms of service for API usage terms.\n\nFile v1.0.0:INTEGRATION-QUESTIONS.md\n\n# ProductAI Integration - Questions for Users\n\nThis document contains the key questions to ask users when setting up ProductAI integration, along with the easiest setup flow.\n\n---\n\n## Pre-Integration Questions\n\n### 1. Do you have a ProductAI account?\n\n**If NO:**\n- Direct them to: **[https://www.productai.photo](https://www.productai.photo)**\n- They need to sign up and choose a plan (Basic, Standard, or Pro)\n- Wait for them to complete signup\n\n**If YES:**\n- Proceed to question 2\n\n---\n\n### 2. Do you have a ProductAI API key?\n\n**If NO:**\n- Guide them: \"Go to ProductAI Studio → **API Access** → Generate API Key\"\n- Wait for them to copy the key\n- **Important:** Remind them to keep it secret!\n\n**If YES:**\n- Ask them to have it ready (they'll paste it in setup)\n\n---\n\n### 3. What plan are you on?\n\nOptions:\n- **Basic** ($8/month) — 70 + 20 free credits\n- **Standard** ($16/month) — 250 + 20 free credits\n- **Pro** ($49/month) — 950 + 20 free credits\n\nThis helps set expectations for token usage.\n\n---\n\n### 4. What will you use ProductAI for?\n\nCommon answers:\n- E-commerce product photos (clean backgrounds, lifestyle shots)\n- Marketing campaigns (hero images, social media)\n- Batch processing product catalogs\n- Creative compositing (multi-image scenes)\n- Image upscaling for print/high-res\n\nThis helps recommend the right model and workflow.\n\n---\n\n## Super Easy Setup Flow\n\n### Step 1: Verify They Have an API Key\n\n```\nAgent: \"To use ProductAI, you'll need an API key. Do you have one?\"\n\nUser: \"No\" → Guide to productai.photo, wait\nUser: \"Yes\" → Proceed\n```\n\n---\n\n### Step 2: Run Setup\n\n**Option A: Interactive (User runs script)**\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nThe script asks:\n1. **API Key:** User pastes key\n2. **API Endpoint:** [Press Enter for default]\n3. **Default Model:** [Press Enter for nanobanana]\n4. **Default Resolution:** [Press Enter for 1024x1024]\n5. **Your Plan:** basic / standard / pro\n\n**Option B: Agent-Driven (Programmatic)**\n\n```python\n# Agent collects API key in conversation\napi_key = user_message  # e.g., \"sk_prod_abc123...\"\n\n# Agent creates config\nimport json\nfrom pathlib import Path\n\nconfig = {\n    \"api_key\": api_key,\n    \"api_endpoint\": \"https://api.productai.photo/v1\",\n    \"default_model\": \"nanobanana\",\n    \"default_resolution\": \"1024x1024\",\n    \"plan\": \"standard\"  # Or ask user\n}\n\nconfig_path = Path.home() / '.openclaw' / 'workspace' / 'productai' / 'config.json'\nconfig_path.parent.mkdir(parents=True, exist_ok=True)\n\nwith open(config_path, 'w') as f:\n    json.dump(config, f, indent=2)\n\nconfig_path.chmod(0o600)\n\n# Confirm to user\nprint(\"✓ ProductAI configured! Your API key is saved securely.\")\n```\n\n---\n\n### Step 3: Test It Immediately\n\n**Run a quick test to confirm setup works:**\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://i.imgur.com/sample.jpg\" \\\n  --prompt \"white background\" \\\n  --output test.png\n```\n\n**If successful:**\n```\n✓ Job created: 12345\nWaiting for completion...\n✓ Generation complete!\nDownloading image to test.png...\n✓ Saved to test.png\n```\n\n**If failed:**\n- `401 Unauthorized` → Invalid API key (ask user to regenerate)\n- `OUT_OF_TOKENS` → No credits left (ask user to purchase more)\n- Other errors → Check error message and guide user\n\n---\n\n## Making API Key Input Super Easy\n\n### Best Practices\n\n**✅ DO:**\n1. **Provide direct link:** \"Get your key here: [https://www.productai.photo/api-access](https://www.productai.photo)\"\n2. **Show exactly where to find it:** \"Look for **API Access** in your dashboard\"\n3. **Auto-validate:** Test the API key immediately after setup\n4. **Give clear feedback:** \"✓ API key valid!\" or \"❌ Invalid key, please check and try again\"\n5. **Secure it automatically:** Set file permissions to 600 (user-only read/write)\n\n**❌ DON'T:**\n1. Ask for info you can auto-detect (API endpoint, default model)\n2. Show raw JSON or complex config formats\n3. Leave users wondering if setup worked (always test!)\n4. Display the API key in logs or responses (security!)\n\n---\n\n## Sample Conversation Flow\n\n```\nAgent: \"Ready to set up ProductAI! Do you have an API key?\"\n\nUser: \"No\"\n\nAgent: \"No problem! Here's what to do:\n\n1. Visit https://www.productai.photo\n2. Log in (or sign up if you're new)\n3. Go to **API Access**\n4. Copy your API key\n\nLet me know when you have it!\"\n\n---\n\nUser: \"Got it: sk_prod_abc123xyz\"\n\nAgent: \"Perfect! Setting that up now...\"\n[Creates config.json programmatically]\n\nAgent: \"✓ API key saved securely!\n\nWant to test it? Send me a product image URL and I'll generate \na version with a clean white background.\"\n\n---\n\nUser: \"https://example.com/watch.jpg\"\n\nAgent: [Runs generate_photo.py]\n\"Here's your product with a white studio background! 🎨\n[Sends generated image]\n\nCost: 3 tokens (Nano Banana model)\n\nWhat else would you like to create?\"\n```\n\n---\n\n## Error Recovery\n\n### Invalid API Key (401)\n\n```\nAgent: \"Hmm, that API key didn't work. Here's what to check:\n\n1. Make sure you copied the full key (starts with 'sk_prod_')\n2. Verify it's active in ProductAI Studio → API Access\n3. Try regenerating a new key if needed\n\nWant to try again?\"\n```\n\n---\n\n### Out of Tokens\n\n```\nAgent: \"You're out of tokens! Here's how to get more:\n\n- **Purchase tokens:** Visit productai.photo\n- **Upgrade plan:** Get more monthly credits with Standard or Pro\n\nYour current plan: [plan]\n\nLet me know when you're ready to continue!\"\n```\n\n---\n\n### Rate Limited (429)\n\n```\nAgent: \"ProductAI has a rate limit of 15 requests/minute. \nLet's wait a moment before trying again...\"\n\n[Auto-retry after 10 seconds]\n```\n\n---\n\n## Key Takeaways\n\n1. **Minimize friction:** Only ask what you absolutely need (API key, plan)\n2. **Validate immediately:** Test the API key right after setup\n3. **Provide clear guidance:** Direct links, step-by-step, screenshots\n4. **Handle errors gracefully:** Clear messages + recovery steps\n5. **Make it conversational:** Feel like talking to a helpful human\n\n---\n\n**Goal:** User gets from \"I want to use ProductAI\" to \"Here's my first generated image\" in under 2 minutes.\n\nFile v1.0.0:QUICKSTART.md\n\n# ProductAI Quick Start Guide\n\nGet started with ProductAI in 5 minutes.\n\n## Step 1: Get Your API Key\n\n1. Visit **[ProductAI Studio](https://www.productai.photo)**\n2. Click on **API Access** in the navigation\n3. Find or generate your API key\n4. Copy it to clipboard\n\n> **Where to find it:**\n> \n> ![API Access Screenshot - Shows where to find your API key in the ProductAI dashboard]\n\n## Step 2: Run Setup\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nWhen prompted:\n- **API Key:** Paste your key from Step 1\n- **API Endpoint:** Press Enter (uses default: `https://api.productai.photo/v1`)\n- **Default Model:** Press Enter (uses `nanobanana`)\n- **Default Resolution:** Press Enter (uses `1024x1024`)\n- **Your Plan:** Enter your plan (`basic`, `standard`, or `pro`)\n\nThe setup script will:\n- Create `config.json` with your settings\n- Secure the file (permissions: 600)\n- Confirm everything is ready\n\n## Step 3: Generate Your First Image\n\nTry a simple generation:\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/your-product.jpg\" \\\n  --prompt \"white studio background with soft lighting\" \\\n  --output my-first-result.png\n```\n\n**What happens:**\n1. API request sent to ProductAI\n2. Job created (you'll see the job ID)\n3. Script polls for completion (~5-30 seconds)\n4. Image downloads to `my-first-result.png`\n\n## Common Use Cases\n\n### Clean Product Backgrounds\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/messy-bg.jpg\" \\\n  --prompt \"pure white background\" \\\n  --output clean.png\n```\n\n### Lifestyle Shots\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/watch.jpg\" \\\n  --prompt \"wrist wearing the watch, business attire, office desk background\" \\\n  --output lifestyle.png\n```\n\n### Combine Multiple Products\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/lipstick.jpg\" \"https://example.com/box.jpg\" \\\n  --prompt \"Place the lipstick on top of the cosmetic box\" \\\n  --model nanobanana \\\n  --output combo.png\n```\n\n### High Quality (Nano Banana Pro)\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"luxury marble countertop, golden hour lighting\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n> **Note:** Nano Banana Pro costs 8 tokens vs 3 for regular models\n\n### Upscale for Print\n\n```bash\n./scripts/upscale_image.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --output upscaled.png\n```\n\n> **Note:** Upscaling costs 20 tokens\n\n## Available Models\n\n| Model | Token Cost | Best For |\n|-------|------------|----------|\n| `gpt-low` | 2 | Quick tests, drafts |\n| `gpt-medium` | 3 | Standard quality |\n| `gpt-high` | 8 | High quality |\n| `kontext-pro` | 3 | Product placement |\n| `nanobanana` | 3 | **Default** — fast & good |\n| `nanobananapro` | 8 | Premium quality |\n| `seedream` | 3 | Creative scenes |\n\n**Multi-image support:** `nanobanana`, `nanobananapro`, `seedream` (max 2 images)\n\n## Async Workflow (For Batch Jobs)\n\nInstead of waiting for each job, start them all and check later:\n\n```bash\n# Start 3 jobs (collect job IDs)\n./scripts/generate_photo.py --image \"url1\" --prompt \"prompt1\" --no-wait  # → Job ID: 101\n./scripts/generate_photo.py --image \"url2\" --prompt \"prompt2\" --no-wait  # → Job ID: 102\n./scripts/generate_photo.py --image \"url3\" --prompt \"prompt3\" --no-wait  # → Job ID: 103\n\n# Later, download results\n./scripts/generate_photo.py --job-id 101 --output result1.png\n./scripts/generate_photo.py --job-id 102 --output result2.png\n./scripts/generate_photo.py --job-id 103 --output result3.png\n```\n\n## Troubleshooting\n\n### \"Config file not found\"\nRun `./scripts/setup.py` first.\n\n### \"OUT_OF_TOKENS\"\nCheck your token balance in ProductAI Studio. Purchase more tokens or upgrade plan.\n\n### \"Invalid API key\" (401)\nRegenerate your API key in ProductAI Studio → API Access.\n\n### Job stuck at \"RUNNING\"\nJobs usually complete in 5-30 seconds. If stuck after 5 minutes, check ProductAI Studio for service status.\n\n### Image not downloaded\nCheck that the image URL is publicly accessible and under 10MB (PNG, JPG, or WebP).\n\n## Next Steps\n\n- Read [SKILL.md](SKILL.md) for full feature documentation\n- Check [API.md](references/API.md) for detailed API reference\n- Explore batch processing with `batch_generate.py`\n- Set up webhooks for production workflows\n\n## Support\n\n- **Website:** https://www.productai.photo\n- **API Docs:** [references/API.md](references/API.md)\n- **Issues:** Contact ProductAI support via dashboard\n\n---\n\n**Happy generating! 🚀**\n\nFile v1.0.0:SECURITY.md\n\n# Security Features & Mitigations\n\nThis document outlines the security measures implemented in the ProductAI skill.\n\n## Security Fixes Applied\n\n### ✅ Fixed Issues\n\n#### 1. URL Validation & SSRF Prevention\n**Issue:** Image URLs accepted without validation, potential SSRF attacks  \n**Fix:** `productai_client.py:validate_image_url()`\n- **HTTPS-only:** Rejects HTTP URLs\n- **Private network blocking:** Prevents access to:\n  - localhost / 127.x.x.x\n  - Private IPs (10.x.x.x, 172.16-31.x.x, 192.168.x.x)\n  - Link-local addresses (169.254.x.x)\n  - IPv6 localhost/link-local (::1, fe80::)\n- Applied to all image URL inputs in `generate()` and `upscale()`\n\n#### 2. Request Timeouts\n**Issue:** HTTP requests without timeouts could hang indefinitely  \n**Fix:** Added 30-second timeout to all requests:\n- `productai_client.py`: All API calls (`DEFAULT_TIMEOUT = 30`)\n- `generate_photo.py`: Image downloads\n- `upscale_image.py`: Image downloads\n- `batch_generate.py`: Image downloads\n\n#### 3. Rate Limiting (Batch Processing)\n**Issue:** No rate limiting despite 15 req/min API limit  \n**Fix:** `batch_generate.py`\n- Enforces 4-second minimum between requests (15 req/min = 4s interval)\n- Default max workers: 3 (to stay comfortably under limit)\n- Sequential request submission with `time.sleep()` between requests\n\n#### 4. Path Traversal Prevention\n**Issue:** Unsanitized filenames in batch processing  \n**Fix:** `batch_generate.py:sanitize_filename()`\n- Removes path separators (`/`, `\\`)\n- Blocks parent directory references (`..`)\n- Allows only alphanumeric, dash, underscore, dot\n- Prevents hidden files (leading `.`)\n\n---\n\n## Acceptable Trade-offs\n\n### Plain Text API Key Storage\n**Rationale:**\n- Industry standard for CLI tools (AWS CLI, gcloud, stripe-cli all do this)\n- File permissions set to `600` (user read/write only)\n- Alternative (OS keychain) adds complexity and dependencies\n- Users can use environment variables if preferred: `PRODUCTAI_API_KEY`\n\n**Mitigation:**\n- Config file: `chmod 600` (user-only access)\n- API key never logged or displayed in output\n- Clear documentation warns users to keep keys secure\n\n---\n\n## Security Best Practices for Users\n\n### 1. Protect Your API Key\n- Never commit `config.json` to version control\n- Don't share your API key in chat, logs, or screenshots\n- Regenerate key if accidentally exposed\n\n### 2. Use HTTPS URLs Only\n- The skill enforces HTTPS-only image URLs\n- Avoids exposing API keys over unencrypted connections\n\n### 3. Monitor API Usage\n- Check ProductAI dashboard regularly for unexpected usage\n- Rate limits prevent runaway costs\n\n### 4. Keep Dependencies Updated\n- Run `pip install --upgrade requests` periodically\n- Monitor security advisories for Python dependencies\n\n---\n\n## Implementation Details\n\n### URL Validation (`productai_client.py`)\n\n```python\n@staticmethod\ndef validate_image_url(url: str) -> None:\n    \"\"\"Validate image URL for security.\"\"\"\n    parsed = urlparse(url)\n    \n    # Only allow HTTPS\n    if parsed.scheme != 'https':\n        raise ValueError(f\"Only HTTPS URLs are allowed. Got: {parsed.scheme}://\")\n    \n    # Block private/local network addresses (SSRF prevention)\n    hostname = parsed.hostname\n    if not hostname:\n        raise ValueError(\"Invalid URL: missing hostname\")\n    \n    # Block localhost, private IPs, link-local\n    blocked_patterns = [\n        r'^localhost$',\n        r'^127\\.',\n        r'^10\\.',\n        r'^172\\.(1[6-9]|2[0-9]|3[01])\\.',\n        r'^192\\.168\\.',\n        r'^169\\.254\\.',\n        r'^::1$',\n        r'^fe80:',\n    ]\n    \n    for pattern in blocked_patterns:\n        if re.match(pattern, hostname, re.IGNORECASE):\n            raise ValueError(f\"Private/local addresses are not allowed: {hostname}\")\n```\n\n### Request Timeouts\n\nAll HTTP requests include explicit timeouts:\n\n```python\n# API calls\nresponse = self.session.post(url, json=payload, timeout=30)\n\n# Image downloads\nresponse = requests.get(url, stream=True, timeout=30)\n```\n\n### Rate Limiting (`batch_generate.py`)\n\n```python\nRATE_LIMIT_SECONDS = 4.0  # 15 req/min = 4s interval\n\nfor image_url in image_urls:\n    # Rate limiting: ensure minimum time between requests\n    elapsed = time.time() - last_request_time\n    if elapsed < RATE_LIMIT_SECONDS:\n        time.sleep(RATE_LIMIT_SECONDS - elapsed)\n    \n    # Submit job\n    future = executor.submit(process_single_image, ...)\n    last_request_time = time.time()\n```\n\n### Filename Sanitization (`batch_generate.py`)\n\n```python\ndef sanitize_filename(filename: str) -> str:\n    \"\"\"Sanitize filename to prevent path traversal.\"\"\"\n    # Remove path separators and parent references\n    safe_name = filename.replace('/', '_').replace('\\\\', '_').replace('..', '_')\n    \n    # Keep only safe characters\n    safe_name = re.sub(r'[^a-zA-Z0-9._-]', '_', safe_name)\n    \n    # Prevent hidden files\n    if safe_name.startswith('.'):\n        safe_name = '_' + safe_name[1:]\n    \n    return safe_name\n```\n\n---\n\n## Testing\n\nAll security fixes have been tested:\n\n### URL Validation Tests\n```bash\n✓ Valid HTTPS URL accepted\n✓ HTTP blocked: Only HTTPS URLs are allowed. Got: http://\n✓ Localhost blocked: Private/local addresses are not allowed: localhost\n✓ Private IP blocked: Private/local addresses are not allowed: 192.168.1.1\n```\n\n### Filename Sanitization Tests\n```bash\n✓ \"normal.jpg\" → \"normal.jpg\"\n✓ \"../../../etc/passwd\" → \"______etc_passwd\"\n✓ \"file/with/slashes.png\" → \"file_with_slashes.png\"\n✓ \".hidden\" → \"_hidden\"\n✓ \"file with spaces.jpg\" → \"file_with_spaces.jpg\"\n```\n\n### Integration Test\n```bash\n✓ Real image generation with HTTPS URL: Success\n✓ HTTP URL rejection: Blocked as expected\n✓ Request timeout: All requests complete within 30s\n```\n\n---\n\n## Reporting Security Issues\n\nIf you discover a security vulnerability in this skill:\n\n1. **Do NOT open a public issue**\n2. Contact the skill maintainer directly\n3. Provide details: affected code, reproduction steps, potential impact\n4. Allow reasonable time for a fix before public disclosure\n\n---\n\n## Version History\n\n**v1.1.0** (2026-02-23)\n- Added URL validation (HTTPS-only, SSRF prevention)\n- Added request timeouts (30s default)\n- Added rate limiting for batch processing\n- Added filename sanitization\n\n**v1.0.0** (2026-02-22)\n- Initial release\n\n---\n\n**Security is a shared responsibility.** Keep your API keys secure, monitor usage, and report issues promptly.\n\nFile v1.0.0:SETUP-GUIDE.md\n\n# ProductAI Integration Setup Guide\n\n**Goal:** Make getting your ProductAI API key and integrating it with OpenClaw as easy as possible.\n\n## For End Users: Getting Started\n\n### Step 1: Get Your ProductAI API Key\n\n**Option A: If you already have a ProductAI account**\n\n1. Go to **[https://www.productai.photo](https://www.productai.photo)**\n2. Log in to your account\n3. Navigate to **API Access** (in the dashboard/settings)\n4. You'll see your API key displayed — copy it\n5. If no key exists, click **Generate API Key**\n\n**Option B: If you're new to ProductAI**\n\n1. Go to **[https://www.productai.photo](https://www.productai.photo)**\n2. Sign up for an account\n3. Choose a plan (Basic, Standard, or Pro)\n4. Once logged in, go to **API Access**\n5. Generate your first API key\n\n**⚠️ Important:** Keep your API key secret! Don't share it publicly or commit it to version control.\n\n### Step 2: Run the Setup Script\n\nOpen your terminal and run:\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nThe script will ask you a few questions:\n\n**Q: API Key:**\nPaste the key you copied from ProductAI Studio.\n\n**Q: API Endpoint:**\nJust press Enter (uses default: `https://api.productai.photo/v1`)\n\n**Q: Default Model:**\nPress Enter (uses `nanobanana` — good balance of speed and quality)\n\n**Q: Default Resolution:**\nPress Enter (uses `1024x1024`)\n\n**Q: Your Plan:**\nEnter `basic`, `standard`, or `pro` depending on your ProductAI subscription.\n\n**That's it!** Your configuration is saved and secured.\n\n### Step 3: Test It\n\nRun a quick test to make sure everything works:\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/test-product.jpg\" \\\n  --prompt \"white background\" \\\n  --output test.png\n```\n\nIf you see:\n```\n✓ Job created: 12345\n  Status: RUNNING\n\nWaiting for completion...\n\n✓ Generation complete!\nImage URL: https://...\nDownloading image to test.png...\n✓ Saved to test.png\n```\n\n**You're all set!** 🎉\n\n---\n\n## For Skill Creators: Integration Checklist\n\nWhen building a ProductAI integration for OpenClaw users, here's what to prepare:\n\n### Pre-Integration Questions to Ask\n\n**1. Account Status**\n- Do you have a ProductAI account? (Yes / No)\n- If yes, which plan? (Basic / Standard / Pro)\n\n**2. API Access**\n- Have you generated an API key? (Yes / No)\n- If yes, do you have it handy?\n\n**3. Use Case**\n- What will you use ProductAI for?\n  - E-commerce product photos?\n  - Marketing campaigns?\n  - Social media content?\n  - Other?\n\n### Setup Flow\n\n**Path A: User has API key already**\n```\n1. Run setup script\n2. Paste API key\n3. Test with sample generation\n4. Done!\n```\n\n**Path B: User needs to get API key**\n```\n1. Direct to productai.photo\n2. Guide through signup/login\n3. Navigate to API Access\n4. Copy key\n5. Run setup script\n6. Paste key\n7. Test\n8. Done!\n```\n\n### Making It \"Super Easy\"\n\n**✅ DO:**\n- Provide direct links to API Access page\n- Show screenshots of where to find the key\n- Auto-detect common issues (missing config, invalid key)\n- Test API key immediately after setup\n- Give clear success/failure messages\n- Provide example commands users can copy-paste\n\n**❌ DON'T:**\n- Ask for information you can auto-detect (endpoint URL, default model)\n- Require manual JSON editing\n- Show raw error messages without explanation\n- Leave users wondering if setup worked\n\n### Sample Setup Conversation Flow\n\n```\nAgent: \"Hey! To use ProductAI, I'll need your API key. Do you have one?\"\n\nUser: \"No\"\n\nAgent: \"No problem! Here's how to get one:\n\n1. Visit https://www.productai.photo\n2. Sign up or log in\n3. Go to API Access\n4. Copy your API key\n\nLet me know when you have it!\"\n\nUser: \"Got it: sk_prod_abc123...\"\n\nAgent: \"Perfect! Setting that up now...\"\n[Runs setup script programmatically]\n\nAgent: \"✓ API key saved and tested! Want to try generating an image?\"\n\nUser: \"Sure\"\n\nAgent: \"Great! Send me a product image URL and tell me what background you want.\"\n\nUser: \"https://example.com/watch.jpg — modern office desk\"\n\nAgent: [Runs generate_photo.py]\n\"Here's your result! [image]\"\n```\n\n### Error Handling\n\n**Invalid API Key (401)**\n```\nAgent: \"Hmm, that API key didn't work. Double-check it in ProductAI Studio → API Access. \nWant to try again or regenerate a new key?\"\n```\n\n**Out of Tokens**\n```\nAgent: \"Looks like you're out of tokens. You can:\n- Purchase more tokens at productai.photo\n- Upgrade your plan for more monthly credits\n\nLet me know when you're ready to try again!\"\n```\n\n**Rate Limited (429)**\n```\nAgent: \"ProductAI has a rate limit of 15 requests/minute. Let's wait a bit before trying again.\"\n[Auto-retry after delay]\n```\n\n---\n\n## Technical Implementation Notes\n\n### Config File Structure\n\n```json\n{\n  \"api_key\": \"sk_prod_...\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\n- Stored at: `~/.openclaw/workspace/productai/config.json`\n- Permissions: `600` (user read/write only)\n- Never log or display the API key\n\n### Testing the API Key\n\nAfter setup, immediately test with a simple API call:\n\n```python\nimport requests\n\nresponse = requests.get(\n    \"https://api.productai.photo/v1/api/job/1\",  # Dummy job ID\n    headers={\"x-api-key\": api_key}\n)\n\nif response.status_code == 401:\n    print(\"❌ Invalid API key\")\nelif response.status_code in [200, 404]:\n    print(\"✓ API key valid!\")\nelse:\n    print(f\"⚠️ Unexpected response: {response.status_code}\")\n```\n\n### Programmatic Setup (For Agents)\n\nAgents can run setup programmatically instead of interactively:\n\n```python\nimport json\nfrom pathlib import Path\n\nconfig = {\n    \"api_key\": user_provided_key,\n    \"api_endpoint\": \"https://api.productai.photo/v1\",\n    \"default_model\": \"nanobanana\",\n    \"default_resolution\": \"1024x1024\",\n    \"plan\": user_plan or \"standard\"\n}\n\nconfig_path = Path.home() / '.openclaw' / 'workspace' / 'productai' / 'config.json'\nconfig_path.parent.mkdir(parents=True, exist_ok=True)\n\nwith open(config_path, 'w') as f:\n    json.dump(config, f, indent=2)\n\nconfig_path.chmod(0o600)\n```\n\n---\n\n## FAQ\n\n**Q: Do I need to install anything?**\nA: Python dependencies are auto-installed. Just run the setup script.\n\n**Q: Can I change my API key later?**\nA: Yes! Just run `./scripts/setup.py` again and it will overwrite the old config.\n\n**Q: Where is my API key stored?**\nA: In `~/.openclaw/workspace/productai/config.json` (secured with 600 permissions).\n\n**Q: Can I use this with multiple ProductAI accounts?**\nA: You can only have one API key configured at a time. To switch accounts, run setup again.\n\n**Q: What if I run out of tokens?**\nA: Visit ProductAI Studio to purchase more or upgrade your plan.\n\n**Q: How do I know how many tokens I have left?**\nA: Check your ProductAI Studio dashboard for current balance.\n\n---\n\n**Questions or issues?** Check [SKILL.md](SKILL.md) or [API.md](references/API.md) for more details.\n\nFile v1.0.0:config.example.json\n\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n\nFile v1.0.0:package.json\n\n{\n  \"name\": \"productai\",\n  \"version\": \"1.1.0\",\n  \"description\": \"Generate professional AI product photos using ProductAI.photo service. Supports background replacement, product placement, scene generation, and upscaling for e-commerce and marketing.\",\n  \"author\": \"Shape Team\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"image-generation\",\n    \"product-photography\",\n    \"ai\",\n    \"e-commerce\",\n    \"marketing\",\n    \"background-replacement\",\n    \"upscaling\"\n  ],\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/shape-team/productai-skill\"\n  },\n  \"main\": \"SKILL.md\",\n  \"scripts\": {\n    \"setup\": \"python3 scripts/setup.py\",\n    \"generate\": \"python3 scripts/generate_photo.py\",\n    \"upscale\": \"python3 scripts/upscale_image.py\",\n    \"batch\": \"python3 scripts/batch_generate.py\"\n  },\n  \"dependencies\": {\n    \"python\": \">=3.7\",\n    \"requests\": \">=2.25.0\"\n  },\n  \"clawhub\": {\n    \"category\": \"productivity\",\n    \"difficulty\": \"beginner\",\n    \"setup_required\": true,\n    \"api_key_required\": true\n  }\n}","readmeExcerpt":"Skill: Generate product photos for ecommerce Owner: shapes-2 Summary: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-02-24T13:03:31.529Z | user • Updated API documentation with all the official endpoints from your file • Added new models: kontext-max • Doc","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"cd ~/.openclaw/workspace/productai\nscripts/setup.py\n# Paste your API key when prompted"},{"language":"bash","snippet":"# Generate product photo with custom background\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"modern living room with natural lighting\" \\\n  --output result.png\n\n# Use multiple reference images (nanobanana/seedream support 2 images)\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Put the first image on top of the second image\" \\\n  --output result.png\n\n# High quality with Nano Banana Pro\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"white studio background\" \\\n  --model nanobananapro \\\n  --output hq.png\n\n# Upscale an image (20 tokens)\nscripts/upscale_image.py \\\n  --image https://example.com/photo.jpg \\\n  --output upscaled.png"},{"language":"bash","snippet":"cd ~/.openclaw/workspace/productai\nscripts/setup.py"},{"language":"json","snippet":"{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nanobanana\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}"},{"language":"bash","snippet":"pip install requests pillow"},{"language":"bash","snippet":"scripts/generate_photo.py \\\n  --image https://example.com/raw-product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output store-listing.png"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: productai\ndescription: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, marketing, catalogs, or campaigns. Supports background replacement, product placement, scene generation, adaptive templates, and video ads. Use for tasks involving product photography, lifestyle shots, mockups, or marketing visuals.\n---\n\n# ProductAI Integration\n\nProductAI.photo is an AI-powered service that generates professional product photos from existing images. It enables e-commerce businesses, marketers, and designers to create studio-quality product photography without hiring photographers.\n\n## Quick Start\n\n**1. Get Your API Key**\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your API key\n\n**2. Run Setup**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n# Paste your API key when prompted\n```\n\n**3. Generate Images**\n\n```bash\n# Generate product photo with custom background\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"modern living room with natural lighting\" \\\n  --output result.png\n\n# Use multiple reference images (nanobanana/seedream support 2 images)\nscripts/generate_photo.py \\\n  --image https://example.com/product1.jpg https://example.com/product2.jpg \\\n  --prompt \"Put the first image on top of the second image\" \\\n  --output result.png\n\n# High quality with Nano Banana Pro\nscripts/generate_photo.py \\\n  --image https://example.com/product.jpg \\\n  --prompt \"white studio background\" \\\n  --model nanobananapro \\\n  --output hq.png\n\n# Upscale an image (20 tokens)\nscripts/upscale_image.py \\\n  --image https://example.com/photo.jpg \\\n  --output upscaled.png\n```\n\n## Core Capabilities\n\n**Photo Generation (`/api/generate`)**\n- Background replacement with AI-generated scenes\n- Product placement in realistic environments\n- Multi-image compositing (up to 2 reference images with certain models)\n- Custom prompts for full creative control\n\n**Image Upscaling (`/api/upscale`)**\n- Professional AI upscaling (Magnific Precision Upscale)\n- Preserves image details without distortion\n- 20 tokens per upscale\n\n**Models Available**\n- **gpt-low** — GPT Low Quality (2 tokens)\n- **gpt-medium** — GPT Medium Quality (3 tokens)\n- **gpt-high** — GPT High Quality (8 tokens)\n- **kontext-pro** — Kontext Pro (3 tokens)\n- **nanobanana** — Nano Banana (3 tokens) — **DEFAULT**\n- **nanobananapro** — Nano Banana Pro (8 tokens)\n- **seedream** — Seedream (3 tokens)\n\n**Multi-Image Support:**\n`nanobanana`, `nanobananapro`, and `seedream` support up to 2 reference images for advanced compositing.\n\n## Configuration\n\n### API Setup\n\n**Step 1: Get Your API Key**\n\n1. Visit [ProductAI Studio](https://www.productai.photo)\n2. Navigate to **API Access** section\n3. Click **Generate API Key** or copy existing key\n\n**Step 2: Run Setup Script**\n\n```bash\ncd ~/.openclaw/workspace/productai\nscripts/setup.py\n```\n\nThis will interactively c"},{"path":"README.md","content":"# ProductAI Integration for OpenClaw\n\nGenerate professional AI product photos directly from OpenClaw using the ProductAI.photo API.\n\n## What is ProductAI?\n\nProductAI.photo is an AI-powered service that transforms product images with:\n- Background replacement and scene generation\n- Multi-image compositing\n- Professional upscaling\n- Multiple AI models for different quality levels\n\nPerfect for e-commerce, marketing, and content creation.\n\n## Quick Links\n\n- **[ProductAI Website](https://www.productai.photo)** — Sign up & get API key\n- **[Quick Start Guide](QUICKSTART.md)** — Get running in 5 minutes\n- **[Setup Guide](SETUP-GUIDE.md)** — Detailed setup instructions & FAQ\n- **[Skill Documentation](SKILL.md)** — Full feature reference\n- **[API Reference](references/API.md)** — Complete API documentation\n\n## Installation\n\n### 1. Get Your API Key\n\nVisit [ProductAI Studio](https://www.productai.photo) → **API Access** → Copy your key\n\n### 2. Run Setup\n\n```bash\ncd ~/.openclaw/workspace/productai\n./scripts/setup.py\n```\n\nPaste your API key when prompted. That's it!\n\n### 3. Generate Images\n\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"white studio background\" \\\n  --output result.png\n```\n\n## Available Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `setup.py` | Configure API credentials |\n| `generate_photo.py` | Generate product photos |\n| `upscale_image.py` | Upscale images (20 tokens) |\n| `batch_generate.py` | Batch process multiple images |\n\n## Common Use Cases\n\n### Clean Product Backgrounds\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/messy.jpg\" \\\n  --prompt \"pure white background\" \\\n  --output clean.png\n```\n\n### Lifestyle Photography\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/watch.jpg\" \\\n  --prompt \"wrist wearing watch, business setting\" \\\n  --output lifestyle.png\n```\n\n### Multi-Image Compositing\n```bash\n./scripts/generate_photo.py \\\n  --image \"url1\" \"url2\" \\\n  --prompt \"Combine both products\" \\\n  --model nanobanana \\\n  --output combo.png\n```\n\n### High Quality (Nano Banana Pro)\n```bash\n./scripts/generate_photo.py \\\n  --image \"https://example.com/product.jpg\" \\\n  --prompt \"luxury marble countertop\" \\\n  --model nanobananapro \\\n  --output premium.png\n```\n\n## Models & Pricing\n\n| Model | Cost | Quality |\n|-------|------|---------|\n| `gpt-low` | 2 tokens | Low |\n| `gpt-medium` | 3 tokens | Medium |\n| `nanobanana` | 3 tokens | **Recommended** |\n| `kontext-pro` | 3 tokens | Good |\n| `seedream` | 3 tokens | Creative |\n| `gpt-high` | 8 tokens | High |\n| `nanobananapro` | 8 tokens | Premium |\n| **Upscale** | 20 tokens | — |\n\n**Multi-image support:** `nanobanana`, `nanobananapro`, `seedream` (max 2 images)\n\n## Documentation\n\n- **New users:** Start with [QUICKSTART.md](QUICKSTART.md)\n- **Setup help:** See [SETUP-GUIDE.md](SETUP-GUIDE.md)\n- **Feature reference:** Read [SKILL.md](SKILL.md)\n- **API details:** Check [API.md](references/API.md)\n- **Security:** See [SEC"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn747nct6wegm6yhndknwfj27s81q02v\",\n  \"slug\": \"productai-skill\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1771938211529\n}"},{"path":"references/API.md","content":"# ProductAI API Reference\n\nComplete documentation for ProductAI.photo public API endpoints.\n\n## Base URL\n\n```\nhttps://api.productai.photo/v1\n```\n\n## Authentication\n\nAll API requests require authentication via the `x-api-key` header:\n\n```bash\ncurl -H \"x-api-key: YOUR_API_KEY\" https://api.productai.photo/v1/api/generate\n```\n\n**Rate Limiting:** 15 requests per minute per IP address.\n\n---\n\n## `/api/generate` — Generate AI Product Photos\n\nGenerate an AI-edited image from one or more input images with a text prompt.\n\n### Endpoint\n\n```\nPOST /api/generate\n```\n\n### Request Body\n\n| Field           | Type                   | Required | Description                                                                                                                                                                              |\n| --------------- | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `image_url`     | `string` or `string[]` | Yes      | URL(s) of input image(s). Maximum 2 images.                                                                                                                                              |\n| `prompt`        | `string`               | Yes      | Text prompt describing the desired edit/generation.                                                                                                                                      |\n| `model`         | `string`               | Yes      | One of: `gpt-low`, `gpt-medium`, `gpt-high`, `kontext-pro`, `kontext-max`, `nanobanana`, `nanobananapro`, `seedream`                                                                    |\n| `output_format` | `string`               | No       | `\"png\"` (default) or `\"jpg\"` / `\"jpeg\"`                                                                                                                                                 |\n| `aspect_ratio`  | `string`               | No       | `\"SQUARE\"`, `\"LANDSCAPE\"`, `\"PORTRAIT\"`. For `nanobanana`/`nanobananapro` also supports: `\"LANDSCAPE_4_3\"`, `\"LANDSCAPE_5_4\"`, `\"SQUARE_1_1\"`, `\"PORTRAIT_4_5\"`, `\"PORTRAIT_3_4\"`, or direct ratios like `\"4:3\"`, `\"9:16\"`, etc. |\n| `resolution`    | `string`               | No       | For `nanobanana`/`nanobananapro` only: `\"1K\"`, `\"2K\"` (default), or `\"4K\"`                                                                                                               |\n\n### Models & Pricing\n\n| Model          | Credits | Engine        |\n| -------------- | ------- | ------------- |\n| `gpt-low`      | 2       | GPT (Lambda)  |\n| `gpt-medium`   | 3       | GPT (Lambda)  |\n| `gpt-high`     | 8       | GPT (Lambda)  |\n| `kontext-pro`  | 2       | FAL           |\n| `kontext-max`  | 3       | FAL           |\n| `nanobanana`   | 3       | FAL           |\n| `nanobananapro`| 8       | FAL           |\n| `seedream` "},{"path":"references/INTEGRATION_GUIDE.md","content":"# ProductAI Integration Guide\n\nComplete guide for integrating ProductAI into your applications, workflows, and AI agents.\n\n## Quick Start (5 minutes)\n\n### 1. Install the Skill\n\n```bash\n# If skill is packaged as .skill file\nopenclaw skills install productai.skill\n\n# Or clone directly\ngit clone https://github.com/your-org/productai-skill ~/.openclaw/workspace/productai\n```\n\n### 2. Configure API Credentials\n\n```bash\ncd ~/.openclaw/workspace/productai\npython3 scripts/setup.py\n```\n\nOr manually create `config.json`:\n\n```json\n{\n  \"api_key\": \"your-api-key-here\",\n  \"api_endpoint\": \"https://api.productai.photo/v1\",\n  \"default_model\": \"nano-banana-2\",\n  \"default_resolution\": \"1024x1024\",\n  \"plan\": \"standard\"\n}\n```\n\n### 3. Test It\n\n```bash\n# Generate your first photo\nscripts/generate_photo.py \\\n  --image product.jpg \\\n  --prompt \"white studio background with soft shadows\" \\\n  --output result.png\n```\n\n**Done!** You now have ProductAI integrated.\n\n## Integration Patterns\n\n### Pattern 1: Command-Line Scripts\n\nBest for: Manual workflows, batch jobs, cron tasks\n\n```bash\n# Single photo generation\nscripts/generate_photo.py --image product.jpg --prompt \"modern living room\" --output result.png\n\n# Background replacement\nscripts/generate_photo.py --image product.jpg --background-replace --output clean.png\n\n# Batch processing\nscripts/batch_generate.py \\\n  --input-dir ./products \\\n  --output-dir ./processed \\\n  --template \"white background with subtle shadows\"\n```\n\n### Pattern 2: Python Library\n\nBest for: Python applications, Jupyter notebooks, automation scripts\n\n```python\nfrom productai_client import create_client\n\n# Initialize client\nclient = create_client()\n\n# Generate photo\nresult = client.generate(\n    image='product.jpg',\n    prompt='modern living room with natural lighting'\n)\n\n# Download result\nclient.download_result(result['image_url'], 'output.png')\n\nprint(f\"Credits used: {result['credits_used']}\")\nprint(f\"Processing time: {result['processing_time_ms']}ms\")\n```\n\n### Pattern 3: AI Agent Integration\n\nBest for: OpenClaw agents, LangChain, AutoGPT, other AI systems\n\n**OpenClaw Integration:**\n\nThe skill is auto-loaded when OpenClaw detects product photo tasks. Just ask:\n\n> \"Generate a professional product photo of this bottle in a modern kitchen setting\"\n\n**Custom Agent Integration:**\n\n```python\nimport subprocess\nimport json\n\ndef generate_product_photo(image_path: str, prompt: str) -> dict:\n    \"\"\"Call ProductAI from any AI agent.\"\"\"\n    result = subprocess.run(\n        [\n            'python3',\n            '/path/to/productai/scripts/generate_photo.py',\n            '--image', image_path,\n            '--prompt', prompt,\n            '--output', 'result.png'\n        ],\n        capture_output=True,\n        text=True\n    )\n    \n    return json.loads(result.stdout)\n\n# Use in your agent\nresult = generate_product_photo('product.jpg', 'white background')\nprint(f\"Generated: {result['image_url']}\")\n```\n\n### Pattern 4: REST API Wrapper\n\nBest for: Microservices, web apps, team a"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma... Skill: Generate product photos for ecommerce Owner: shapes-2 Summary: Generate professional AI product photos using ProductAI.photo service. Use when users need to create, enhance, or transform product images for e-commerce, ma... Tags: latest:1.0.1 Version history: v1.0.1 | 2026-02-24T13:03:31.529Z | user • Updated API documentation with all the official endpoints from your file • Added new models: kontext-max • Doc","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1225,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:56:59.186Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T15:19:58.022Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}