# Pixshop - Full API Documentation for AI Agents
# https://pixshop.app
# Version: 1.0.0

## Authentication

All API calls (except public reads) require a Supabase JWT Bearer token.

### Login

```
POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "..."
}

Response:
{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "user": { "id": "...", "email": "..." }
}
```

Use the access_token as:
```
Authorization: Bearer eyJ...
```

### Check Session

```
GET /api/auth/session
Authorization: Bearer <token>

Response:
{
  "user": { "id": "...", "email": "...", "isPremium": true },
  "credits": 50
}
```

---

## Tool Discovery

### GET /api/agent/discover

Returns all available tools with full JSON Schema definitions for inputs and outputs.

```
GET /api/agent/discover

Response:
{
  "service": { "name": "Pixshop", "baseUrl": "https://pixshop.app", ... },
  "auth": { "type": "bearer", "header": "Authorization: Bearer <token>" },
  "tools": [
    {
      "id": "image-generate",
      "name": "Image Generate",
      "description": "Generate images from text prompts",
      "category": "generation",
      "credits": 2,
      "requiresAuth": true,
      "inputSchema": { "type": "object", "properties": { ... } },
      "outputSchema": { "type": "object", "properties": { ... } }
    },
    ...
  ],
  "categories": [...],
  "stats": { "totalTools": 28 }
}
```

### GET /api/agent/skills

List skills with filtering support.

Query params: `category`, `keyword`, `tags` (comma-separated)

```
GET /api/agent/skills?category=editing
GET /api/agent/skills?keyword=background
```

---

## Agent Chat (Tool Execution)

### POST /api/agent/chat

Send a message to the agent, which can invoke tools automatically.

```
POST /api/agent/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "sessionId": "optional-session-id",
  "message": "Generate an image of a sunset over mountains",
  "attachments": []
}

Response (streamed):
{
  "type": "text",
  "content": "I'll generate that image for you..."
}
{
  "type": "tool-call",
  "toolName": "image-generate",
  "args": { "prompt": "sunset over mountains, golden hour, dramatic clouds" }
}
{
  "type": "tool-result",
  "data": { "imageUrl": "https://..." }
}
```

---

## Credits System

Each tool call consumes credits. Free tools cost 0 credits.

### GET /api/credits/balance

```
Authorization: Bearer <token>

Response:
{
  "credits": 50,
  "tier": "premium"
}
```

### Credit Costs by Tool

| Tool | Credits |
|------|---------|
| image-generate | 2 |
| flux-generate | 3 |
| video-generate | 6 |
| image-edit | 1 |
| image-inpaint | 2 |
| background-remove | 1 |
| style-transfer | 2 |
| outpaint | 3 |
| reference-guide | 3 |
| image-fusion | 2 |
| texture-transfer | 2 |
| age-transform | 2 |
| virtual-tryon | 2 |
| id-photo | 2 |
| image-upscale | 3 |
| product-placement | 3 |
| product-showcase | 3 |
| ecommerce-template | 2 |
| inflate | 2 |
| melt | 2 |
| explode | 2 |
| cakeify | 2 |
| prompt-search | 0 |
| prompt-recommend | 0 |
| app-list | 0 |
| app-execute | varies |
| post-publish | 0 |
| remix-start | 0 |

---

## Tool Details

### image-generate
Generate images from text prompts.
- Input: `prompt` (string, required), `aspectRatio` ("1:1"|"16:9"|"9:16", default "1:1"), `quality` ("standard"|"hd", default "standard")
- Output: `imageUrl` (string), `prompt` (string)

### flux-generate
High-quality image generation using the Flux model.
- Input: `prompt` (string, required), `aspectRatio` (string), `steps` (number)
- Output: `imageUrl` (string)

### video-generate
Generate video from a source image with motion.
- Input: `imageUrl` (string, required), `prompt` (string, required), `duration` ("5"|"10"|"15"), `motionType` ("zoom-in"|"zoom-out"|"pan-left"|"pan-right"|"orbit"|"static")
- Output: `videoUrl` (string), `duration` (number)

### image-edit
Edit an existing image with AI instructions.
- Input: `imageUrl` (string, required), `prompt` (string, required), `editType` (string)
- Output: `imageUrl` (string)

### image-inpaint
Edit masked regions of an image.
- Input: `imageUrl` (string, required), `maskUrl` (string, required), `prompt` (string, required), `quality` ("low"|"medium"|"high")
- Output: `imageUrl` (string)

### background-remove
Remove image background.
- Input: `imageUrl` (string, required), `outputFormat` ("png"|"webp"), `refineEdges` (boolean), `backgroundColor` (string, optional)
- Output: `imageUrl` (string), `hasTransparency` (boolean)

### style-transfer
Convert image to an artistic style.
- Input: `imageUrl` (string, required), `style` ("anime"|"oil-painting"|"watercolor"|"sketch"|"cyberpunk"|"ghibli"|"pixel-art"|"minimalist"), `strength` (number, 0-1)
- Output: `imageUrl` (string), `style` (string)

### outpaint
Extend image beyond its borders.
- Input: `imageUrl` (string, required), `direction` (string), `prompt` (string)
- Output: `imageUrl` (string)

### reference-guide
Generate image using reference guidance.
- Input: `referenceImageUrl` (string, required), `prompt` (string, required), `guidanceStrength` (number)
- Output: `imageUrl` (string)

### image-fusion
Fuse multiple images together.
- Input: `mainImageUrl` (string, required), `sourceImageUrls` (string[], 1-3 images, required), `prompt` (string, required)
- Output: `imageUrl` (string)

### texture-transfer
Apply texture effects to images.
- Input: `imageUrl` (string, required), `texturePrompt` (string, required), `preset` ("vintage"|"paper"|"canvas"|"grunge"|"watercolor"|"noise"|"custom")
- Output: `imageUrl` (string), `texture` (string)

### age-transform
Transform image to a different decade style.
- Input: `imageUrl` (string, required), `decade` ("1920s"|"1950s"|"1970s"|"1980s"|"1990s"), `style` (string, optional)
- Output: `imageUrl` (string), `decade` (string)

### virtual-tryon
Virtual clothing try-on.
- Input: `productImageUrl` (string, required), `personImageUrl` (string, required), `fitAdjustment` (number, 10-50)
- Output: `imageUrl` (string), `images` (string[])

### id-photo
Generate professional ID photos.
- Input: `imageUrl` (string, required), `background` (string, default "white"), `clothing` (string), `photoSpec` ("auto"|"one_inch"|"two_inch"|"us_visa"), `studioLighting` (boolean), `naturalRetouch` (boolean), `autoCompose` (boolean)
- Output: `imageUrl` (string), `spec` (string)

### image-upscale
Upscale image resolution.
- Input: `imageUrl` (string, required), `scale` ("2x"|"4x"), `enhanceDetails` (boolean)
- Output: `imageUrl` (string), `scale` (string)

### prompt-search
Search the curated prompt library.
- Input: `query` (string), `categoryMain` (string), `limit` (number)
- Output: `prompts` (array of prompt objects)

### prompt-recommend
Get AI-powered prompt recommendations.
- Input: `description` (string, required), `limit` (number)
- Output: `prompts` (array)

### app-list
List available Nano Banana AI apps.
- Input: `search` (string, optional), `limit` (number)
- Output: `apps` (array)

### app-execute
Execute a specific AI app.
- Input: `appId` (string, required), `params` (object)
- Output: varies by app

### post-publish
Publish a creation to the community.
- Input: `imageUrl` (string, required), `title` (string), `description` (string), `tags` (string[])
- Output: `postId` (string), `url` (string)

### remix-start
Start a remix from an existing post.
- Input: `postId` (string, required)
- Output: `sessionId` (string), `originalPost` (object)

### inflate / melt / explode / cakeify
Creative visual effects (Pika-style).
- Input: `imageUrl` (string, required), `prompt` (string, optional), `strength` (number, optional)
- Output: `videoUrl` (string) or `imageUrl` (string)

### product-placement
Place a product into a scene.
- Input: `productImageUrl` (string, required), `scenePrompt` (string, required)
- Output: `imageUrl` (string)

### product-showcase
Generate product showcase images.
- Input: `productImageUrl` (string, required), `style` (string), `background` (string)
- Output: `imageUrl` (string)

### ecommerce-template
Apply e-commerce templates to product images.
- Input: `productImageUrl` (string, required), `templateId` (string, required)
- Output: `imageUrl` (string)

---

## REST API Endpoints (Non-Agent)

### Prompt Library
- GET /api/prompt-library?page=1&per_page=20&category_id=X&search=keyword&tags=tag1,tag2
- GET /api/prompt-library/[id]
- POST /api/prompt-library (auth required)

### Apps
- GET /api/apps?page=1&per_page=20&search=keyword
- GET /api/apps/[id]

### Posts (Community)
- GET /api/posts?page=1&per_page=20
- GET /api/posts/[id]
- POST /api/posts (auth required)
- POST /api/posts/[id]/like (auth required)
- POST /api/posts/[id]/comment (auth required)

### Search
- GET /api/search?q=keyword&type=prompts|apps|posts

---

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| AUTH_REQUIRED | 401 | Authentication token missing or invalid |
| INSUFFICIENT_CREDITS | 402 | Not enough credits for this operation |
| SKILL_NOT_FOUND | 404 | Requested tool does not exist |
| SKILL_VALIDATION_FAILED | 400 | Input validation failed |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Server error |

## Rate Limits

- Free tier: 10 requests/minute
- Premium: 60 requests/minute
- Enterprise: Custom

---

## Contact

- Website: https://pixshop.app
- Support: https://pixshop.app/support
- Privacy: https://pixshop.app/privacy
- Terms: https://pixshop.app/terms