# AI Image Combiner — Remote MCP Server & Claude Skill

> **Combine, merge, and blend multiple photos into a single AI-generated image.**
> Free API · MCP-ready · No local GPU required · Works with Claude, Cursor, and any MCP client

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://aiimgcombiner.com/api/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![API Status](https://img.shields.io/badge/API-Live-brightgreen)](https://aiimgcombiner.com)
[![Version](https://img.shields.io/badge/version-1.0.0-orange)](https://aiimgcombiner.com/changelog)

---

## What Is AI Image Combiner?

**[AI Image Combiner](https://aiimgcombiner.com)** is a cloud-based AI photo editing service that lets you **merge two or more photos** into a single, coherent result image using generative AI.

Whether you need a **wedding photo collage**, an **AI couple avatar**, a **hairstyle preview**, or a **birthday card doodle**, this service handles it through a simple REST API or via the MCP (Model Context Protocol) integration directly inside your AI assistant.

This repository ships:

| Asset | Path | Description |
|---|---|---|
| MCP Server Manifest | `mcp/server.json` | Plug-and-play remote MCP config |
| Claude Skill | `skill/ai-img-combiner/SKILL.md` | Ready-to-install Claude Code skill |
| cURL Examples | `examples/curl.sh` | Runnable REST API reference |

---

## Key Features

- **AI-powered image merging** — combine 2+ photos into one using generative models
- **Style prompts** — describe how to blend images with natural language
- **Normal & High quality** — choose processing quality per task
- **Async job queue** — submit tasks, poll results; no blocking calls
- **API Key auth** — per-user credit system, auditable and revocable
- **Remote MCP** — no local installation; works over HTTPS with any MCP client
- **Streamable HTTP transport** — standards-compliant MCP 2025 protocol

---

## Quick Start — MCP (Claude / Cursor)

Add to your MCP client config:

```json
{
  "mcpServers": {
    "aiimgcombiner": {
      "url": "https://aiimgcombiner.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

1. Get a free API key at **[aiimgcombiner.com](https://aiimgcombiner.com)** → Settings → API Keys
2. Paste the config above into your MCP client
3. Use natural language: *"Combine these two photos into a couple avatar"*

---

## Quick Start — REST API (curl)

```bash
export API_KEY="your_api_key_here"

# 1. Upload image — returns CDN URL
UPLOAD=$(curl -sS -X POST https://aiimgcombiner.com/api/open/v1/upload \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "photo.webp",
    "mimeType": "image/webp",
    "dataBase64": "<BASE64_IMAGE>"
  }')
IMAGE_URL=$(echo "$UPLOAD" | jq -r '.url')

# 2. Submit combine task — returns jobId
TASK=$(curl -sS -X POST https://aiimgcombiner.com/api/open/v1/tasks/image-combine \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"payload\": {
      \"imageUrls\": [\"$IMAGE_URL\", \"https://cdn.example.com/b.webp\"],
      \"stylePrompt\": \"Blend these two portraits into a couple avatar with soft lighting.\",
      \"quality\": \"normal\"
    }
  }")
JOB_ID=$(echo "$TASK" | jq -r '.jobId')

# 3. Poll status until completed
curl -sS "https://aiimgcombiner.com/api/open/v1/tasks/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY"
```

Full runnable example: [`examples/curl.sh`](examples/curl.sh)

---

## API Reference

### Endpoints

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/api/open/v1/upload` | Upload a base64 image, get CDN URL |
| `POST` | `/api/open/v1/tasks/image-combine` | Submit a combine job, get `jobId` |
| `GET` | `/api/open/v1/tasks/{taskId}` | Poll job status and result |

### MCP Tools (when using MCP client)

| Tool | Description |
|---|---|
| `upload_image` | Upload image, returns `url` |
| `combine_images` | Submit job, returns `jobId` |
| `get_task_status` | Poll job, returns `resultUrl` when done |

### Status Codes

| Code | Meaning |
|---|---|
| `401` | Invalid or missing API Key |
| `402` | Insufficient credits |
| `404` | Task not found or not owned by this key |
| `500` | Server-side error |

---

## Tool Pages

All tools available at **[aiimgcombiner.com](https://aiimgcombiner.com)**:

| Tool | URL |
|---|---|
| Combine Two Photos | [/combine-two-photos](https://aiimgcombiner.com/combine-two-photos) |
| Photo Collage Maker | [/photo-collage-maker](https://aiimgcombiner.com/photo-collage-maker) |
| Wedding Photo Combiner | [/wedding-photo-combiner](https://aiimgcombiner.com/wedding-photo-combiner) |
| AI Couple Avatar Maker | [/ai-couple-avatar-maker](https://aiimgcombiner.com/ai-couple-avatar-maker) |
| AI Hairstyle Changer | [/ai-hairstyle-changer](https://aiimgcombiner.com/ai-hairstyle-changer) |
| AI Birthday Doodle Maker | [/ai-birthday-doodle-maker](https://aiimgcombiner.com/ai-birthday-doodle-maker) |

---

## Pricing

| Plan | Credits | Features |
|---|---|---|
| Free | Starter credits on signup | All tools, normal quality |
| Pro (Monthly / Yearly) | Monthly replenishment | Priority queue, high quality |
| Lifetime | One-time purchase | All future tools included |

→ **[aiimgcombiner.com/pricing](https://aiimgcombiner.com/pricing)**

---

## Resources

| Resource | URL |
|---|---|
| Official Docs | [aiimgcombiner.com/docs](https://aiimgcombiner.com/docs) |
| Blog & Tutorials | [aiimgcombiner.com/blog](https://aiimgcombiner.com/blog) |
| Changelog | [aiimgcombiner.com/changelog](https://aiimgcombiner.com/changelog) |

---

## Technical Details

- **MCP Protocol**: 2025-12-11, `streamable-http` transport
- **Auth**: `Authorization: Bearer <API_KEY>`
- **Base URL**: `https://aiimgcombiner.com`
- **MCP Endpoint**: `https://aiimgcombiner.com/api/mcp`

---

## Best Practices

- Compress images to ≤2 MB before upload to reduce queue time
- Poll every 2–5 seconds; avoid burst polling
- Use `quality: "high"` only for final output; `"normal"` is faster
- Store `resultUrl` promptly — CDN links may expire after 24 hours
- Use separate API Keys per project for clean audit trails

---

## Repository Structure

```
aiimgcombiner-mcp-skill/
├── README.md
├── mcp/
│   └── server.json                 # MCP server manifest
├── skill/
│   └── ai-img-combiner/
│       └── SKILL.md                # Claude Code skill definition
└── examples/
    └── curl.sh                     # Runnable curl example
```

---

*Powered by [aiimgcombiner.com](https://aiimgcombiner.com)*