# Assets & Collections
Source: https://pixelcut.ai/docs/agents/asset-management

Upload, organize, and search your media assets from MCP.

Assets are the images and videos in your Pixelcut workspace. Collections let you organize them into groups. Both are fully manageable from the MCP server.

## Assets

### MCP tools

The `assets` tool supports `list`, `search`, and `get` actions. Use the `upload` tool to import from URLs or get a one-time upload URL for local files.

| Action                  | Description                                                      |
| ----------------------- | ---------------------------------------------------------------- |
| `assets` (`list`)       | List assets, with optional filters by collection, tag, or status |
| `assets` (`search`)     | Search by keyword or semantic similarity                         |
| `assets` (`get`)        | Fetch metadata and a fresh URL for a single asset                |
| `upload` (`url`)        | Import an image from a public URL                                |
| `upload` (`upload_url`) | Get a one-time upload URL for a local file                       |

### Importing files

Ask the agent to import an image from a URL:

```
Import this product photo into my workspace: https://example.com/photo.jpg
```

The agent calls `upload` with `action: "url"` and returns the new asset ID:

```json theme={null}
{
  "id": "ast_abc123",
  "url": "https://assets.pixelcut.app/ast_abc123.png",
  "content_type": "image/png"
}
```

### Listing and filtering

```
List the assets in my "Summer Campaign" collection.
```

```
Find product photos tagged "hero" that are ready to use.
```

The agent calls `assets` with `action: "list"` and the appropriate filters (`collection_id`, `tag`, or `status`).

### Searching assets

Search uses semantic similarity — describe what you are looking for in natural language:

```
Find images of red sneakers on a white background.
```

<Info>
  Semantic search requires a Business tier subscription.
</Info>

## Collections

Collections are named groups of assets. Use them to organize uploads, target batch operations, and keep related assets together.

### MCP actions

The `collections` tool supports `list`, `search`, `get`, and `create` actions.

| Action                   | Description                |
| ------------------------ | -------------------------- |
| `collections` (`list`)   | List all collections       |
| `collections` (`search`) | Search collections by name |
| `collections` (`get`)    | Get a collection by ID     |
| `collections` (`create`) | Create a new collection    |

### Creating a collection

```
Create a new collection called "Summer Campaign" and put the images we just generated into it.
```

The agent calls `collections` (action: `create`), then references the new collection ID in subsequent operations.

## Common workflows

### Organize generated content

```
Generate 5 product shots, then save them all to a new "Q3 Hero Shots" collection.
```

The agent calls `generate_media` to produce the images, `collections` (`create`) for the new collection, and includes the `collection_id` so generated assets land directly in the right place.

### Find and process

```
Find my outdoor furniture photos and remove the background from the best one.
```

The agent calls `assets` (`search`), then `edit_image` with `action: "remove_background"` on the chosen result.

<Info>
  You cannot delete assets, collections, or share links via MCP. Use the Pixelcut web app for deletion.
</Info>


# Brand Libraries
Source: https://pixelcut.ai/docs/agents/brand-libraries

Manage brand identities and generate brand-consistent content from MCP.

Brand libraries store your brand identity — name, website, tagline, and description. When you generate content with a brand library attached, Pixelcut uses that identity to produce on-brand results.

## Setting up a brand library

Brand libraries are created and edited in the Pixelcut web app. See the [Brand Libraries guide](/docs/user-guide/key-features/brand) for setup instructions.

Once created, your agent can list and reference brand libraries through MCP.

## Listing brand libraries

Ask the agent to find your brand libraries:

```
What brand libraries do I have in my workspace?
```

The agent calls `assets` or the brand-aware generation flow to surface available brand library IDs and identity details.

## Using a brand library with generation

Pass the brand library ID to `generate_media` to apply your brand identity to any generation task:

```
Generate a social media banner for our summer sale using our Acme brand.
```

The agent locates the brand library by name, then calls `generate_media` with the matching `brand_library_id`. Generated images follow the brand's visual guidelines — consistent colors, typography, and style.

### Generation parameters with brand

| Parameter          | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `brand_library_id` | Brand library to apply (recommended for any branded asset)       |
| `aspect_ratio`     | Match the platform — `1:1` for Instagram, `16:9` for web banners |
| `num_variations`   | Generate multiple options to pick the best on-brand result       |

## End-to-end workflow

```
Using our Acme brand, generate 3 Instagram-ready announcement graphics for our new product line, plus a 3:1 email header.
```

The agent:

1. Finds the Acme brand library and pulls the matching `brand_library_id`.
2. Calls `generate_media` with `brand_library_id`, `aspect_ratio: "1:1"`, and `num_variations: 3` for the Instagram posts.
3. Calls `generate_media` again with the same `brand_library_id` and `aspect_ratio: "3:1"` for the email header.

<Tip>
  Generate multiple variations with `num_variations` to pick the best result while maintaining brand consistency across all options.
</Tip>

<Info>
  For more on brand libraries and how to configure brand identities in the web app, see the [Brand Libraries guide](/docs/user-guide/key-features/brand).
</Info>


# Editing Tools
Source: https://pixelcut.ai/docs/agents/editing-tools

Remove backgrounds, upscale, and expand images with AI.

Edit images using natural-language prompts through the Pixelcut MCP server. All results are saved to your workspace.

## Background removal

Use `edit_image` with `action: "remove_background"`:

```
Remove the background from this product photo.
```

The output is a transparent PNG with the subject cleanly isolated. Supports batch processing — pass an array of images to process them in parallel.

## Upscale

Use `edit_image` with `action: "upscale"` and optional `scale` parameter (`"2"` or `"4"`):

```
Upscale this photo to 4x.
```

## Expand / outpaint

Use `edit_image` with `action: "expand"`. You can specify pixel amounts per direction (`left`, `right`, `top`, `bottom`) or use `aspect_ratio` (e.g., `"16:9"`) to auto-calculate the padding:

```
Expand this square image to 16:9 for a website banner.
```

## Chaining operations

Run multiple editing steps in sequence by passing the output asset ID of one step into the next.

```
Remove the background from this product photo, then upscale the result 4x.
```

The agent will call `edit_image` (action: `remove_background`), then call `edit_image` again (action: `upscale`, scale: `"4"`) with the resulting asset ID.

For repeatable multi-step workflows, consider creating a [pipeline](/docs/agents/pipelines) instead.

## Batch editing

The `edit_image` tool accepts an array of images for batch processing:

```
Upscale all the images in my 'Product Shots' collection to 4x.
```

The agent calls `assets` to list the collection contents, then `edit_image` with an array of asset IDs.

## Editing tools summary

| Operation          | MCP action                               |
| ------------------ | ---------------------------------------- |
| Background removal | `edit_image` action: `remove_background` |
| Upscale (2x/4x)    | `edit_image` action: `upscale`           |
| Expand/outpaint    | `edit_image` action: `expand`            |

## Related

* [Remove Background (User Guide)](/docs/user-guide/core-workflows/remove-background) -- in-app background removal
* [Upscale (User Guide)](/docs/user-guide/core-workflows/upscale) -- in-app upscaling
* [MCP Server](/docs/agents/mcp) -- full MCP tool reference


# Image Generation
Source: https://pixelcut.ai/docs/agents/image-generation

Generate images from text prompts, reference images, or natural-language editing instructions.

Generate product photos, marketing visuals, and design concepts by describing what you want. Attach reference images for more control. All results are saved to your Pixelcut workspace.

## Text-to-image

Use the `generate_media` tool with a prompt and model ID. Call `models` (action: `list`) first to find available model IDs:

```
Generate a studio product photo of a water bottle on a marble countertop.
```

The agent calls `models` to find a model, then `generate_media` with the chosen model ID and prompt.

## Reference-based generation

Pass image URLs or asset IDs in the `attachments` parameter of `generate_media`. The model uses the attachment as a visual reference while composing the new scene:

```
Generate a lifestyle scene of this product on a kitchen counter with morning light.
```

## Generation parameters

The `generate_media` tool accepts:

| Parameter          | Description                               | Example                                 |
| ------------------ | ----------------------------------------- | --------------------------------------- |
| `prompt`           | The text description (required)           | `"product photo of sneakers on marble"` |
| `model`            | Model ID for generation (required)        | `nano-banana-2`                         |
| `aspect_ratio`     | Output aspect ratio                       | `1:1`, `16:9`, `4:3`, `9:16`            |
| `media_type`       | `image` or `video`                        | `image`                                 |
| `output_format`    | File format                               | `png`, `jpg`, `webp`                    |
| `num_variations`   | Number of variations to produce           | `1`-`4`                                 |
| `attachments`      | Reference image URLs or asset IDs         | —                                       |
| `brand_library_id` | Brand library for brand-consistent output | `lib_abc123`                            |

## Browsing models

The `models` tool supports `list`, `search`, `get`, and `recommend` actions. Use `recommend` with a natural language description of your use case to get ranked suggestions:

```
Find a good model for generating product lifestyle photos.
```

## Batch generation

Generate multiple variations in a single call by setting `num_variations`:

```
Generate 4 lifestyle photos of this watch on a wooden desk.
```

To produce the same concept across different aspect ratios, ask for separate runs:

```
Generate this product shot in 1:1 for Instagram, 16:9 for the website banner, and 9:16 for stories.
```

## Prompt engineering tips

<Tip>
  Write prompts as if briefing a photographer: subject first, then environment, lighting, and mood.
</Tip>

| Technique                     | Example                                               |
| ----------------------------- | ----------------------------------------------------- |
| Be specific about the subject | "white ceramic mug" instead of "a mug"                |
| Describe the environment      | "on a rustic wooden table, blurred garden background" |
| Specify lighting              | "soft natural light from the left, gentle shadows"    |
| Set the mood or style         | "minimal, editorial, high-end product photography"    |
| Mention camera details        | "shot at eye level, shallow depth of field"           |

<Info>
  When passing a `brand_library_id`, the model pulls brand colors, fonts, and style references automatically. Combine this with a descriptive prompt for brand-consistent output.
</Info>

## Related

* [Image Generation (User Guide)](/docs/user-guide/key-features/image-generation) -- in-app generation workflow
* [MCP Server](/docs/agents/mcp) -- full MCP tool reference


# MCP Server
Source: https://pixelcut.ai/docs/agents/mcp

Connect Pixelcut's AI image and video tools to any MCP-compatible agent or IDE.

The Pixelcut MCP server exposes Pixelcut's full suite of AI editing, generation, and asset management tools via the Model Context Protocol. This lets any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, or custom agents — use Pixelcut directly.

## Setup

### Prerequisites

* A Pixelcut account ([sign up here](https://www.pixelcut.ai))
* An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

### Claude

1. Go to **Settings → Connectors → Add Custom Connector**
2. Enter the server URL:

```
https://mcp.pixelcut.ai/mcp
```

### Claude Code

```bash theme={null}
claude mcp add pixelcut --transport http https://mcp.pixelcut.ai/mcp
```

### Other agents

Pixelcut MCP is supported in popular MCP clients like ChatGPT, Codex, Cursor, and more. Add `https://mcp.pixelcut.ai/mcp` as a remote MCP server in your agent or editor's MCP settings. Refer to your client's documentation for the exact config location.

### Verify the connection

Once configured, ask your agent something like:

> "Check my Pixelcut credit balance."

If the agent calls the `account` tool and returns your balance, the connection is working.

***

## Available tools

The MCP server provides 12 tools. Tools that support multiple operations use an `action` parameter.

### Editing

| Tool            | Actions                                  | Description                                                                                      |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **edit\_image** | `remove_background`, `upscale`, `expand` | AI image editing with batch support. Accepts a single image or an array for parallel processing. |

### Generation

| Tool                | Actions                              | Description                                                                                                                     |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **generate\_media** | --                                   | Generate images or videos from a text prompt. Requires a `model` ID (use `models` to find one). Returns a `job_id` immediately. |
| **models**          | `list`, `search`, `get`, `recommend` | Browse and search available AI models. Call `list` before generating to find valid model IDs.                                   |

### Asset management

| Tool             | Actions                                       | Description                                                                      |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
| **assets**       | `list`, `search`, `get`                       | Browse, search, and fetch details for your media assets.                         |
| **upload**       | `url`, `upload_url`                           | Import an image from a public URL, or get a one-time upload URL for local files. |
| **collections**  | `list`, `search`, `get`, `create`             | Organize assets into named groups.                                               |
| **share\_links** | `list`, `get`, `create`, `update`, `contents` | Create shareable links to asset selections or collections.                       |

### Workflows

| Tool                  | Actions                                                                                 | Description                                             |
| --------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **pipelines**         | `list`, `search`, `get`, `run`, `list_runs`, `get_run`, `cancel_run`, `list_node_types` | Inspect and run reusable multi-step workflows.          |
| **display\_pipeline** | --                                                                                      | Render an interactive node graph preview of a pipeline. |

### Account and jobs

| Tool                 | Actions                    | Description                                                                                                       |
| -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **account**          | `credits`, `usage_history` | Check your credit balance and view usage history.                                                                 |
| **get\_job\_status** | --                         | Poll the status of async jobs (generation, edits). Supports `sync: true` to wait up to 25 seconds for completion. |

### Display

| Tool        | Actions | Description                                                                          |
| ----------- | ------- | ------------------------------------------------------------------------------------ |
| **display** | --      | Render a visual gallery of assets or collections. Only available in rich UI clients. |

***

## Examples

### Remove a background

> "Remove the background from this product photo."

The agent calls `edit_image` with `action: "remove_background"` and returns the result with a transparent background.

### Batch upscale

> "Upscale all the images in my 'Product Shots' collection to 4x."

The agent calls `assets` to list the collection contents, then `edit_image` with `action: "upscale"`, `scale: "4"`, and an array of asset IDs.

### Generate an image

> "Generate a studio product photo of a water bottle on a marble countertop."

The agent first calls `models` (action: `list`, type: `image`) to find a model, then calls `generate_media` with the chosen model ID and prompt. The result is an async job — the agent polls `get_job_status` or the UI widget polls automatically.

### Expand for a banner

> "Expand this square image to 16:9 for a website banner."

The agent calls `edit_image` with `action: "expand"` and `aspect_ratio: "16:9"`.

### Run a pipeline

> "Run my 'Hero Banner' pipeline on these three product images."

The agent calls `pipelines` (action: `get`) to inspect the pipeline, then `pipelines` (action: `run`) with the input images mapped to the correct node IDs.

### Share results

> "Create a share link with the images I just generated."

The agent calls `share_links` with `action: "create"` and the `asset_ids` from the generation results.

***

## Limitations

* **Credit consumption.** Generation and editing operations consume credits from your Pixelcut account. Check your balance with `account` (action: `credits`).
* **Temporary URLs.** Result URLs expire. Always use `asset_id` for downstream operations (chaining edits, organizing, sharing). Use `assets` (action: `get`) to get a fresh URL when needed.
* **Async generation.** `generate_media` returns immediately with a `job_id`. The images/videos are not ready until the job completes. In text-only clients, use `get_job_status` with `sync: true` to wait.
* **Semantic search requires Business tier.** The `assets` (action: `search`) tool requires a Business subscription.
* **Rate limits.** The MCP server is subject to the same [rate limits](/docs/developer-guide/core-concepts/rate-limits) as the REST API.
* **No destructive operations.** You cannot delete assets, collections, or share links via MCP. Use the Pixelcut web app for deletion.
* **Share link constraints.** When creating a share link, provide either `asset_ids` or `collection_id` — not both.

***

## Troubleshooting

### Tools not appearing in the client

1. Restart your MCP client after changing the config.
2. Verify you've added `https://mcp.pixelcut.ai/mcp` as the server URL.
3. Check that you've completed the OAuth login when prompted.

### "Unauthorized" or 401 errors

Your session may have expired. Restart the MCP client to trigger a new OAuth login. If using an API key, verify it is valid — generate a new one at [pixelcut.ai/developer-settings](https://www.pixelcut.ai/developer-settings).

### Generation jobs stuck in "running"

Some models take longer than others. Use `get_job_status` with `sync: true` to wait up to 25 seconds. For video generation, jobs can take several minutes — poll periodically rather than using sync mode.

### "Insufficient credits" errors

Check your balance with `account` (action: `credits`). Purchase more credits or upgrade your plan at [pixelcut.ai/developer-settings](https://www.pixelcut.ai/developer-settings).

### "Upgrade required" errors

Some features (like semantic search) require a higher subscription tier. The error response includes an `upgrade_url` — follow it to upgrade your plan.

### Image input not recognized

When passing images to tools, use one of these formats (in order of preference):

1. **Pixelcut asset ID** — e.g., `ast_abc123`
2. **Public HTTP/HTTPS URL** — e.g., `https://example.com/photo.jpg`
3. **Local file** — first call `upload` (method: `upload_url`) to get an upload URL, run the returned `curl` command, then pass the resulting `asset_id`

### File uploads failing in Claude

Claude blocks outgoing network connections by default. To enable file uploads via the `upload` tool:

1. Go to **Settings → Capabilities → Network Egress → Additional allowed domains**
2. Add `*.pixelcut.ai` to the list
3. Start a new chat

### Need more help?

* [API status page](https://status.pixelcut.ai)
* [Contact support](/docs/user-guide/troubleshooting/contact-support)


# Pixelcut for Agents
Source: https://pixelcut.ai/docs/agents/overview

Give AI agents access to Pixelcut's full suite of image and video tools — generation, editing, automation, and asset management.

Give your AI agents access to Pixelcut's full creative toolkit. Describe what you need in natural language and your agent handles the rest — generating images, editing photos, producing videos, running multi-step pipelines, and organizing results. Everything is saved to your Pixelcut workspace, searchable and shared with your team.

## What you can do

| Capability       | What it does                                                           | Learn more                                       |
| ---------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
| Image generation | Create product photos, lifestyle scenes, and visuals from text prompts | [Image Generation](/docs/agents/image-generation)     |
| Video generation | Produce short clips from text or image inputs                          | [Video Generation](/docs/agents/video-generation)     |
| Editing tools    | Remove backgrounds, upscale, expand images with AI                     | [Editing Tools](/docs/agents/editing-tools)           |
| Brand libraries  | Store brand identities and generate on-brand content                   | [Brand Libraries](/docs/agents/brand-libraries)       |
| Pipelines        | Run saved, reusable multi-step workflows                               | [Pipelines](/docs/agents/pipelines)                   |
| Asset management | Upload, search, tag, and organize files                                | [Assets & Collections](/docs/agents/asset-management) |
| Share links      | Create shareable galleries from asset selections                       | [Share Links](/docs/agents/views-and-publishing)      |

## Get started

<CardGroup>
  <Card title="MCP Server" icon="plug" href="/agents/mcp">
    Connect Pixelcut to any MCP-compatible client. Works with Claude Desktop, Claude Code, Cursor, and more.
  </Card>

  <Card title="Editing Tools" icon="wand-magic-sparkles" href="/agents/editing-tools">
    Remove backgrounds, upscale, and expand images with AI.
  </Card>
</CardGroup>

## Go deeper

<CardGroup>
  <Card title="Image Generation" icon="image" href="/agents/image-generation">
    Generate product photos, lifestyle scenes, and marketing visuals from a prompt.
  </Card>

  <Card title="Pipelines" icon="diagram-project" href="/agents/pipelines">
    Run reusable, multi-step workflows on your assets.
  </Card>

  <Card title="Brand Libraries" icon="shapes" href="/agents/brand-libraries">
    Store brand identities and generate on-brand content.
  </Card>

  <Card title="Assets & Collections" icon="folder" href="/agents/asset-management">
    Upload, search, tag, and organize files in your workspace.
  </Card>
</CardGroup>


# Pipelines
Source: https://pixelcut.ai/docs/agents/pipelines

Run multi-step reusable workflows from MCP.

Pipelines are saved multi-step workflows built from nodes — remove background, upscale, generate, and more — chained together in a graph. Create pipelines in the Pixelcut web app, then run them from any MCP-compatible agent.

## Running a pipeline

Use the `pipelines` tool with action `run`:

```
Run my "Product Photo Cleanup" pipeline on these three product images.
```

The agent calls `pipelines` (action: `get`) to inspect the pipeline, then `pipelines` (action: `run`) with inputs mapped to the correct node IDs.

Inputs are mapped by node alias. Values can be public URLs, Pixelcut asset IDs, or text — the agent picks the right type based on the node's input spec.

## MCP actions

The `pipelines` tool supports these actions:

| Action            | Description                               |
| ----------------- | ----------------------------------------- |
| `list`            | List all pipelines                        |
| `search`          | Find pipelines by name                    |
| `get`             | Get pipeline details with nodes and edges |
| `run`             | Start a pipeline execution                |
| `list_runs`       | List runs for a specific pipeline         |
| `get_run`         | Get run details with per-node status      |
| `cancel_run`      | Stop a running execution                  |
| `list_node_types` | Available node types with I/O specs       |

Use `display_pipeline` to render an interactive node graph preview in MCP App UIs.

## Finding pipelines

```
What pipelines do I have for product photos?
```

The agent calls `pipelines` (action: `search`) with the relevant query, or `list` to browse everything available.

## Monitoring runs

Pipeline runs are async. The `pipelines` (action: `run`) call returns a `run_id`. Track progress with:

```
Check the status of my pipeline run.
```

The agent calls `pipelines` (action: `get_run`) to fetch the run state, including per-node status and outputs.

## End-to-end example

```
Run my "Product Cleanup" pipeline on this product photo and save the results to my Q3 Hero Shots collection.
```

The agent:

1. Calls `pipelines` (`search`) to find the "Product Cleanup" pipeline.
2. Calls `pipelines` (`get`) to inspect the input nodes.
3. Calls `pipelines` (`run`) with the photo mapped to the right input and `collection_id` set to the target collection.
4. Polls `pipelines` (`get_run`) until the run completes, then surfaces the resulting assets.

<Info>
  For more on pipeline concepts and the web-based pipeline editor, see the [Pipelines user guide](/docs/user-guide/automate/pipelines).
</Info>


# Video Generation
Source: https://pixelcut.ai/docs/agents/video-generation

Generate videos from text, images, or audio — including talking head and lipsync.

Create short video clips from text prompts, animate still images, or produce talking-head videos with lipsync. All results are saved to your Pixelcut workspace.

## Text-to-video

Use the `generate_media` tool with `media_type: "video"` and a video model:

```
Generate a 5-second product reveal video of sneakers rotating on a white background.
```

## Image-to-video

Pass a start frame as an attachment and describe the motion you want:

```
Animate this product photo with a slow zoom in and subtle background motion.
```

The model uses the attached image as the opening frame and animates from there.

## Talking video

Attach a face image and provide a script — the model animates the face to speak the script with natural lip movement and expression:

```
Make this face say: "Hi everyone, welcome to our product launch. Today we are introducing something special."
```

## Lipsync

Attach both a face image and an audio file to sync lip movement to existing audio:

```
Lipsync this face image to the attached voiceover audio.
```

<Info>
  For lipsync, attach the face image and audio file together as separate `attachments`.
</Info>

## Video parameters

The `generate_media` tool accepts:

| Parameter        | Description                           | Example                              |
| ---------------- | ------------------------------------- | ------------------------------------ |
| `prompt`         | Description of the video (required)   | `"slow pan across a sunlit kitchen"` |
| `model`          | Video model ID (required)             | `kling-v2.6-pro`                     |
| `media_type`     | Set to `"video"` for video generation | `video`                              |
| `aspect_ratio`   | Output aspect ratio                   | `16:9`, `9:16`, `1:1`                |
| `output_format`  | File format                           | `mp4`, `webm`                        |
| `num_variations` | Number of variations                  | `1`-`4`                              |
| `attachments`    | Start frame, face image, or audio     | —                                    |

## Batch video generation

Generate multiple variations:

```
Generate 3 variations of a product reveal animation for this image.
```

To produce the same video in different aspect ratios for different platforms, ask for separate runs:

```
Generate this product demo in 16:9 for YouTube and 9:16 for TikTok.
```

## Tips

<Tip>
  For talking videos, write the script as natural speech. Avoid stage directions or formatting — just write what the person should say.
</Tip>

* **Start frame matters.** For image-to-video, the quality and composition of your start frame directly affects the output.
* **Keep prompts focused.** Describe one clear motion or scene rather than a complex sequence.
* **Async jobs.** Video generation can take several minutes. Use `get_job_status` with `sync: true` to wait up to 25 seconds, or poll periodically for longer jobs.

## Related

* [Video Generation (User Guide)](/docs/user-guide/key-features/video-generation) -- in-app video workflow
* [MCP Server](/docs/agents/mcp) -- full MCP tool reference


# Share Links
Source: https://pixelcut.ai/docs/agents/views-and-publishing

Create shareable links to curated asset selections from MCP.

Share links let you curate a selection of assets into a shareable URL — without moving them out of their collections. Generate or edit images with your agent, organize the results into a share link, and send it to stakeholders.

## MCP actions

The `share_links` tool supports these actions:

| Action     | Description                                         |
| ---------- | --------------------------------------------------- |
| `list`     | List all share links                                |
| `get`      | Get a share link by ID                              |
| `create`   | Create a new share link from assets or a collection |
| `update`   | Add or remove assets from an existing share link    |
| `contents` | List the assets included in a share link            |

## Creating share links

### From specific assets

```
Create a share link called "Summer Collection Lookbook" with the three images we just generated.
```

The agent calls `share_links` with `action: "create"`, the `name`, and the list of `asset_ids` from the most recent results.

### From a collection

```
Create a share link of all images in my "Product Photos" collection.
```

The agent calls `share_links` (`create`) with the `collection_id`.

<Info>
  When creating a share link, provide either `asset_ids` or `collection_id` — not both.
</Info>

## Updating share links

Add or remove assets from an existing share link:

```
Add this new product shot to the "Summer Collection Lookbook" share link, and remove the old version.
```

The agent calls `share_links` (`update`) with `add_asset_ids` and `remove_asset_ids`.

## End-to-end workflow

```
Generate 4 lifestyle photos of these sneakers on a wooden floor, then create a "Sneaker Launch Lookbook" share link with the results.
```

The agent:

1. Calls `generate_media` with the prompt, `num_variations: 4`, and the product attachment.
2. Waits for completion via `get_job_status` (or polls).
3. Calls `share_links` (`create`) with the resulting `asset_ids` and the share link name.
4. Returns the shareable URL.

<Tip>
  The returned share link URL can be sent directly to reviewers, clients, or team members — they don't need a Pixelcut account to view it.
</Tip>

## Use cases

**Product boards** — Collect generated and edited product photos into a shareable link for team review.

**Campaign lookbooks** — Generate brand-consistent images by passing `brand_library_id` to `generate_media`, organize them into a share link, and share with creative leads.

**Client deliverables** — Process a batch of assets via a pipeline, then create a share link as the final deliverable.

<Info>
  For more on views and the visual gallery editor, see the [Views & Galleries guide](/docs/user-guide/automate/views-galleries).
</Info>


# Generate Background
Source: https://pixelcut.ai/docs/api-reference/generate-background

POST /v1/generate-background
Generates a new background for an image. Generated images are 1024x1024 by default.<br/><br/> **Input Image Limits:**
  - Max size: 25MB
  - Min resolution: 64x64px
  - Max resolution: 6000x6000px




# Get Credits
Source: https://pixelcut.ai/docs/api-reference/get-credits

GET /v1/credits
Returns the number of credits remaining in your account.



# API reference
Source: https://pixelcut.ai/docs/api-reference/index

The canonical schema reference for Pixelcut API endpoints.

## Base URL

`https://api.developer.pixelcut.ai`

## Authentication

All requests use an API key header:

```http theme={null}
X-API-Key: sk_...
```

## Endpoints

<CardGroup>
  <Card title="Remove Background" icon="scissors" href="/api-reference/remove-background" />

  <Card title="Upscale" icon="up-right-and-down-left-from-center" href="/api-reference/upscale" />

  <Card title="Generate Background" icon="image" href="/api-reference/generate-background" />

  <Card title="Try On (Beta)" icon="person" href="/api-reference/try-on" />

  <Card title="Get Credits" icon="coins" href="/api-reference/get-credits" />
</CardGroup>


# Outpaint
Source: https://pixelcut.ai/docs/api-reference/outpaint

POST /v1/outpaint
Expands an image by generating AI content beyond its original boundaries. Use this to extend images in any direction while maintaining visual coherence.<br/><br/> **Input Image Limits:**
  - Max size: 25MB
  - Min resolution: 128x128px
  - Max resolution: 6000x6000px
  - Supported formats: JPEG, PNG (PNG will be converted to JPEG for processing)
<br/><br/> **Expansion Limits:**
  - Each direction (left, top, right, bottom) can be extended by 0-2000 pixels
  - At least one direction must have a non-zero value




# Remove Background
Source: https://pixelcut.ai/docs/api-reference/remove-background

POST /v1/remove-background
Removes the background from an image and optionally adds AI-generated shadows, crops to the subject, and applies margins. When AI shadows are requested, an additional 3 credits will be consumed.<br/><br/> **Input Image Limits:**
  - Max size: 25MB
  - Min resolution: 64x64px
  - Max resolution: 6000x6000px




# Try On (Beta)
Source: https://pixelcut.ai/docs/api-reference/try-on

POST /v1/try-on
**BETA** - This endpoint is currently in beta and may change without notice.<br/><br/>
Places a garment onto a person image.<br/><br/>
**For Best Results:**
  - Person Image:
      - There should only be one person in the image.
      - Plain backgrounds and no accessories are best
      - The person should take up most of the frame, a 3/4 body view works best.
      - The person should be standing facing forward, side/seated views work less well.
  - Garment Image:
      - The garment image should only contain a single garment.
      - Plain "stock photos" of garments work best, however the model is capable of transferring garments from one person to another.
      - The garment should take up most of the frame.
      - **Note:** If the garment image contains a person wearing the garment or other objects, garment extraction will be required, which costs an additional 5 credits.

**Limitations:**
  - The API may not work with all garments, it works best with top garments like t-shirts, blouses, etc.
  - Text and fine details in the garment image may not be reproduced perfectly in the resulting image.
  - Colors in the resulting image may be slightly different to the colors in the garment image.

**Input Image Limits:**
  - Max size: 25MB
  - Min resolution: 64x64px
  - Max resolution: 6000x6000px




# Try On Job Cancel (Beta)
Source: https://pixelcut.ai/docs/api-reference/try-on-job-cancel

POST /v1/try-on/job/{jobId}/cancel
**BETA** - This endpoint is currently in beta and may change without notice.<br/><br/>
Cancels a Try On job that is currently pending or running.
When a Try On job is submitted with wait_for_result set to false, it can be cancelled using this endpoint if it hasn't completed yet. Jobs that are already completed or failed cannot be cancelled.




# Try On Job Status (Beta)
Source: https://pixelcut.ai/docs/api-reference/try-on-job-status

GET /v1/try-on/job/{jobId}
**BETA** - This endpoint is currently in beta and may change without notice.<br/><br/>
Checks the status of a Try On job.
When using the Try On API with wait_for_result set to false, it returns a job ID. This endpoint allows you to check the status of that job and retrieve the final result when processing is complete.




# Upscale
Source: https://pixelcut.ai/docs/api-reference/upscale

POST /v1/upscale
Increases the resolution of an image by 2x or 4x. Images may be upscaled to a maximum resolution of 6000x6000px. Upscaled images are returned in JPEG format unless the input image contained alpha channels, in which case the output will be PNG format.<br/><br/> **Input Image Limits:**
  - Max size: 25MB
  - Min resolution: 64x64px
  - Max resolution: 6000x6000px




# Remove Video Background
Source: https://pixelcut.ai/docs/api-reference/video-remove-background

POST /v1/video/remove-background
Removes the background from a video and optionally replaces it with a solid color or makes it transparent.<br/><br/>
**Input Video Limits:**
  - Max size: 100MB
  - Max duration: 60 seconds
  - Supported formats: MP4, MOV, WebM, MKV, GIF
  - Supported codecs: H.264, H.265/HEVC, VP8, VP9, AV1, ProRes
  - Resolution: 64x64 to 4096x4096 pixels




# Video Remove Background Job Cancel
Source: https://pixelcut.ai/docs/api-reference/video-remove-background-job-cancel

POST /v1/video/remove-background/job/{jobId}/cancel
Cancels a Video Remove Background job that is currently pending or running.
Jobs that are already completed or failed cannot be cancelled.




# Video Remove Background Job Status
Source: https://pixelcut.ai/docs/api-reference/video-remove-background-job-status

GET /v1/video/remove-background/job/{jobId}
Checks the status of a Video Remove Background job.
When using the Video Remove Background API, it returns a job ID. This endpoint allows you to check the status of that job and retrieve the final result when processing is complete.




# Credits
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/credits

How to check your remaining credits and monitor your usage.

Pixelcut API uses a credit-based model. Each successful request consumes credits based on the operation.

## When are credits consumed?

In general:

* Credits are consumed on **successful** requests
* Failed requests typically do **not** consume credits
* In some cases (for example, safety moderation), credits may still be consumed

## How to check your remaining credits

Use the `GET /v1/credits` endpoint to fetch your balance programmatically.

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS "https://api.developer.pixelcut.ai/v1/credits" \
    -H "X-API-Key: $PIXELCUT_API_KEY"
  ```

  ```js Node.js theme={null}
  const resp = await fetch('https://api.developer.pixelcut.ai/v1/credits', {
    headers: { 'X-API-Key': process.env.PIXELCUT_API_KEY },
  });
  console.log(await resp.json());
  ```

  ```python Python theme={null}
  import os, requests
  resp = requests.get(
    "https://api.developer.pixelcut.ai/v1/credits",
    headers={"X-API-Key": os.environ["PIXELCUT_API_KEY"]},
  )
  resp.raise_for_status()
  print(resp.json())
  ```
</CodeGroup>

## How to monitor your usage

You can monitor your usage through the **developer dashboard**.


# Error handling
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/error-handling

Build resilient clients with consistent logging and retry behavior.

Most error responses return a JSON body with:

* `error`: human-readable message
* `error_code`: machine-readable code for programmatic handling

## Common status codes

* `400` invalid request (for example: image too large, unsupported format)
* `401` invalid or missing API key (`invalid_auth_token`)
* `403` insufficient credits (`insufficient_api_credits`)
* `429` rate limit exceeded (`rate_limit_exceeded`)
* `500` internal error (retryable)

## 400 error codes (examples)

Common `error_code` values include:

* `missing_parameter`, `invalid_parameter`
* `unsupported_image_format`, `malformed_image`
* `file_size_too_large`, `resolution_too_high`
* `unknown_foreground` (foreground subject not detected)

## Logging recommendations

* Log: endpoint, status code, `error_code`, and a request timestamp
* Redact: API keys, signed URLs, and user PII

<Card title="Rate limits & retries" icon="timer" href="/developer-guide/core-concepts/rate-limits" />


# Image Requirements
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/image-requirements

Supported formats, file size limits, and per-endpoint resolution constraints.

## Supported formats

* Images must be JPEG or PNG format
* File size is limited to **25MB**

## Per-endpoint limits (summary)

* **Remove background**: min `64×64`, max `6000×6000`
* **Generate background**: min `64×64`, max `6000×6000` (outputs are `1024×1024` by default)
* **Upscale**:
  * min `64×64`
  * max input `3000×3000` for 2×, `1500×1500` for 4×
  * max output `6000×6000`
* **Virtual try-on**: min `256×256`, max `1920×1920`

<Card title="Error handling" icon="triangle-exclamation" href="/developer-guide/core-concepts/error-handling" />


# Rate Limits
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/rate-limits

Handle 429s safely with exponential backoff and jitter.

By default, Pixelcut API is rate limited (commonly **5 requests/second** per account). If you exceed the limit, you’ll receive a `429` with `error_code: rate_limit_exceeded`.

## Retry policy (recommended)

* Retry **only** on retryable responses (typically `429` and transient `5xx`)
* Use exponential backoff with jitter
* Add a max retry count and a max backoff cap

## Example backoff logic

```txt theme={null}
delay_ms = min(max_delay, base_delay * 2^attempt) + random(0, jitter)
```

## Example (Node)

```js theme={null}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function withRetries(requestFn, { maxRetries = 5 } = {}) {
  let attempt = 0;
  while (true) {
    const resp = await requestFn();
    if (resp.status !== 429 && resp.status < 500) return resp;

    if (attempt >= maxRetries) return resp;

    const base = 250 * 2 ** attempt;
    const jitter = Math.floor(Math.random() * 250);
    await sleep(Math.min(5_000, base + jitter));
    attempt += 1;
  }
}
```

<Card title="Batch / high-throughput processing" icon="layer-group" href="/user-guide/core-workflows/batch-edit" />


# Request Formats
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/request-formats

When to use JSON vs multipart, and how Accept headers work.

Pixelcut endpoints generally support two request styles:

## JSON with `image_url`

Use this when your image is already hosted (recommended for server-side pipelines).

```bash theme={null}
curl -sS "https://api.developer.pixelcut.ai/v1/upscale" \
  -H "X-API-Key: $PIXELCUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn3.pixelcut.app/product.jpg","scale":2}'
```

## Multipart with file upload

Use this when you want to upload the image bytes directly.

```bash theme={null}
curl -sS "https://api.developer.pixelcut.ai/v1/remove-background" \
  -H "X-API-Key: $PIXELCUT_API_KEY" \
  -H "Accept: application/json" \
  -F "image=@./product.jpg"
```

## `Accept` header: JSON vs image bytes

Some endpoints support:

* `Accept: application/json` → returns `{ "result_url": "..." }`
* `Accept: image/*` → returns the binary image directly

<Tip>
  For production pipelines, `application/json` + downloading `result_url` is usually easier to retry and to store.
</Tip>

<Card title="Result URLs and asset handling" icon="download" href="/developer-guide/core-concepts/result-urls" />


# Handling Results
Source: https://pixelcut.ai/docs/developer-guide/core-concepts/result-urls

How to safely download, store, and cache results.

Many endpoints return a `result_url` that is valid for a limited time (commonly **1 hour**). Treat it as a temporary delivery URL.

## Best practice

1. Download the output immediately
2. Store it in your own storage (S3/GCS/R2, etc.)
3. Serve it from your CDN for end-user delivery

## Download example

```bash theme={null}
curl -L "$RESULT_URL" -o output.png
```

## Avoid broken pipelines

* Don’t enqueue `result_url` for “later” processing without downloading first
* If you need reprocessing, store the original input and your request parameters


# API overview
Source: https://pixelcut.ai/docs/developer-guide/getting-started/api-overview

What the Pixelcut API can do and how to use it in production.

The Pixelcut API is designed to help you easily integrate the same powerful photo editing tools available in the Pixelcut app into your workflows and applications.

## What you can build

* **Background removal** for listings and catalogs
* **Upscaling** for higher-resolution exports
* **Background generation** for studio-style product scenes
* **Virtual try-on** workflows (async job model)
* **Usage monitoring** via credit balance

<CardGroup>
  <Card title="Quickstart (first API call)" icon="bolt" href="/developer-guide/getting-started/quickstart" />

  <Card title="API reference" icon="book" href="/api-reference/index" />
</CardGroup>


# Authentication & CORS
Source: https://pixelcut.ai/docs/developer-guide/getting-started/authentication-cors

Authenticate requests securely.

All Pixelcut API requests require an API key sent as a header:

```http theme={null}
X-API-Key: sk_...
```

## Security best practices

* Store keys in server-side environment variables or a secrets manager
* Rotate keys if you suspect compromise
* Never embed keys in browser or mobile apps

## Example

```bash theme={null}
curl -sS "https://api.developer.pixelcut.ai/v1/credits" \
  -H "X-API-Key: $PIXELCUT_API_KEY"
```

## Browser / CORS guidance

Pixelcut APIs are designed to be called from a secure environment (your servers). Direct browser calls will typically fail due to CORS and would expose your secret key.

### Recommended architecture

* **Browser / client** uploads to **your backend**
* Your backend calls **Pixelcut API** using `X-API-Key`
* Your backend returns a signed URL or stored asset to the client

### Why this matters

* Prevents key leakage (the most common integration mistake)
* Lets you enforce your own auth, quotas, and abuse protection

<Card title="Rate limits & retries" icon="timer" href="/developer-guide/core-concepts/rate-limits" />


# Pricing
Source: https://pixelcut.ai/docs/developer-guide/getting-started/pricing

Where to generate keys, view usage, and manage billing.

## Pricing

Pixelcut API uses a credit-based pricing. Every developer account is automatically granted 100 free credits when they sign up.

<Tip>
  <p>
    Note that API credits are not the same as app credits. API credits are used for API requests, while app credits are used for app usage.
  </p>
</Tip>

### How It Works

1. **Purchase Credits**: Choose the amount of credits you want to purchase the appropriate plan.
2. **Use Credits**: Each **successful** API call will consume credits based on the specific endpoint.
3. **Monitor Usage**: Track your credit balance and usage through your account dashboard or via the Get Credit Balance endpoint.

### Credits Consumption

Credit costs can change over time. The **developer dashboard** is the source of truth for current credit pricing.

#### Image Tools

| Tool                  | Credits per image |
| --------------------- | ----------------: |
| Background Removal    |                 5 |
| Upscaler              |                10 |
| Background Generation |                10 |
| Outpaint              |                10 |
| Try On                |                10 |

#### Video Tools

| Tool                     |                Credits |
| ------------------------ | ---------------------: |
| Video Background Removal | 1 credit per 50 frames |

### Credit Plans

API Credits can be purchased in the following monthly plans.

| API Credits | Price (monthly) |
| ----------- | --------------: |
| 1,000       |            \$10 |
| 5,000       |            \$50 |
| 10,000      |           \$100 |
| 25,000      |           \$250 |
| 50,000      |           \$500 |
| 100,000     |         \$1,000 |
| 250,000     |         \$2,500 |
| 500,000     |         \$5,000 |
| 1,000,000   |        \$10,000 |

<Tip>
  <p>
    For volumes above 1 million credits, please contact us at [api@pixelcut.ai](mailto:api@pixelcut.ai) for a custom quote.
  </p>
</Tip>

### Additional Information

* **Renewal**: API Credits are allocated to your account according to your selected plan and renew at the start of each billing period. API Credits do not rollover between billing periods.
* **Upgrade**: If you upgrade your plan before the end of your current billing cycle, you will receive your new API Credits immediately. However, your existing API Credits will expire at the end of your original billing period. The new API Credits will continue to renew according to your new plan.
* **Downgrade**: If you downgrade your plan before the end of your current billing cycle you will continue to use your existing API Credits until they are exhausted and your new plan will take effect at the next billing period.
* **Flat Rate**: All API Credits are priced at 1 cent each.

For more information or assistance, please contact our support team at [api@pixelcut.ai](mailto:api@pixelcut.ai).


# Quickstart
Source: https://pixelcut.ai/docs/developer-guide/getting-started/quickstart

Make your first request and save the resulting image.

To begin using the Pixelcut API, you'll need an API key. This key allows you to authenticate your requests and access our services.

## 1) Get an API key

Generate an API key in the developer dashboard.

<Card title="Get an API key" icon="key" href="https://www.pixelcut.ai/developer-settings" />

## 2) Call an endpoint (Remove Background)

This example requests `application/json` and returns a `result_url` you can download.

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS "https://api.developer.pixelcut.ai/v1/remove-background" \
    -H "X-API-Key: <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "image_url": "https://cdn3.pixelcut.app/product.jpg"
    }'
  ```

  ```js Node.js theme={null}
  const response = await fetch('https://api.developer.pixelcut.ai/v1/remove-background', {
    method: 'POST',
    headers: {
      'X-API-Key': '<YOUR_API_KEY>',
      'Content-Type': 'application/json',
      'Accept': 'application/json',
    },
    body: JSON.stringify({
      image_url: 'https://cdn3.pixelcut.app/product.jpg',
    }),
  });

  const data = await response.json();
  console.log(data.result_url);
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.post(
    "https://api.developer.pixelcut.ai/v1/remove-background",
    headers={
      "X-API-Key": "<YOUR_API_KEY>",
      "Accept": "application/json",
    },
    json={"image_url": "https://cdn3.pixelcut.app/product.jpg"},
  )

  resp.raise_for_status()
  print(resp.json()["result_url"])
  ```
</CodeGroup>

## 4) Download and store the output

Result URLs are time-limited, so download and store the file in your own storage.

```bash theme={null}
curl -L "$RESULT_URL" -o output.png
```

## Prefer a binary response?

Some endpoints support `Accept: image/*` to return the image bytes directly.

```bash theme={null}
curl -sS "https://api.developer.pixelcut.ai/v1/remove-background" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Accept: image/*" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn3.pixelcut.app/product.jpg"}' \
  -o output.png
```

<Card title="Request formats (JSON vs multipart)" icon="code" href="/developer-guide/core-concepts/request-formats" />


# Background Removal
Source: https://pixelcut.ai/docs/developer-guide/guides/background-removal

Integrate clean cutouts for commerce and catalog workflows.

The background removal API allows you to remove the background from an image and optionally add AI-generated shadows, crop to the subject, and apply margins.

<img alt="Background removal example" />

## What to build with it

* Product listing cutouts with transparency
* Catalog normalization (consistent background removal)
* Preprocessing step for generation workflows

## For Best Results

* Use sharp images with strong subject/background contrast
* Avoid tiny thumbnails and heavy JPEG artifacts

## Limitations

* Does not support translucent materials such as glass.


# Generate Background
Source: https://pixelcut.ai/docs/developer-guide/guides/generate-background

Produce new backgrounds for images.

The background generation API allows you to generate a new background for an image.

<img alt="Background generation example" />

## What to build with it

* Studio-style product scenes
* Seasonal/brand variants for catalogs
* A/B testing creatives without new photo shoots

## Prompt tips

* Mention **lighting** and **surface** (“soft studio light”, “marble countertop”)
* Keep prompts consistent to maintain a brand look

## Limitations

* Small gaps or "thin" areas in the input image may not be reproduced perfectly in the resulting image.


# Outpaint
Source: https://pixelcut.ai/docs/developer-guide/guides/outpaint

Expand images by generating AI content beyond their original boundaries.

The outpaint API expands an image by generating AI content beyond its original boundaries. Use this to extend images in any direction while maintaining visual coherence with the original content.

## What to build with it

* Expand product photos to fit different aspect ratios
* Add more canvas space for marketing materials
* Convert portrait images to landscape (or vice versa)
* Create wider backgrounds for hero images

## Tips

* Start with smaller extensions (100-300px) for more coherent results
* Use lower creativity values (0.2-0.4) when you need the extension to closely match the original
* Higher creativity values (0.6-0.8) work well for abstract or textured backgrounds

## Limitations

* Each direction can extend up to 2000 pixels
* At least one direction must have a non-zero extension value
* PNG inputs are converted to JPEG for processing
* Generated content may not perfectly match complex patterns or text


# Upscale
Source: https://pixelcut.ai/docs/developer-guide/guides/upscale

Create high resolution images by upscaling the input image.

The upscale API produces fast high resolution images by upscaling the input image by 2x or 4x.

## What to build with it

* Higher-resolution marketplace images
* Better-looking thumbnails after cropping
* Print-ready exports (within max output constraints)


# Video Background Removal
Source: https://pixelcut.ai/docs/developer-guide/guides/video-background-removal

Remove backgrounds from videos with AI-powered segmentation.

Remove the background from videos with per-frame AI segmentation and smooth temporal consistency.

<video>
  <source type="video/mp4" />
</video>

## What to build with it

* Product videos with transparent or custom backgrounds
* Social media content with background replacement
* Video preprocessing for compositing workflows

## For Best Results

* Use videos with good subject/background contrast
* Ensure adequate lighting on the subject
* Avoid fast camera motion or heavy motion blur


# Virtual Try-on
Source: https://pixelcut.ai/docs/developer-guide/guides/virtual-try-on

Place a garment onto a person image.

The virtual try-on API allows you to place a garment onto a person by providing a person image and a garment image.

<img alt="Virtual try-on example" />

## Best results

* Person: one person, front-facing, plain background works best
* Garment: one garment, clear view, minimal clutter

## Limitations

* The API may not work with all garments, it works best with top garments like t-shirts, blouses, etc.
* Text and fine details in the garment image may not be reproduced perfectly in the resulting image.
* Colors in the resulting image may be slightly different to the colors in the garment image.


# Changelog
Source: https://pixelcut.ai/docs/developer-guide/resources/api-changelog

Changes to the API

## 2024-07-20

* Initial public release


# Terms of Service
Source: https://pixelcut.ai/docs/developer-guide/resources/api-terms

Key legal entry points and high-level restrictions.

## Terms of service

Pixelcut API terms of service are published here:

* [Pixelcut API Terms of Service](https://pixelcut.notion.site/Pixelcut-API-Terms-of-Service-11b3b550490080d89a91e943d010efdf?pvs=74h)
* [Pixelcut General Privacy Policy](https://www.pixelcut.ai/privacy)

## Acceptable Use

Acceptable use is covered in the terms of service however at a high level you may use the API to create and edit content using images that you have the rights to use.

### Prohibited Uses

* Generating training data for your own models
* Creating content that is illegal or violates legal rights of others (e.g. copyright, trademark, patent, etc.)
* Creating sexually explicit content
* Creating content that contains violence, self-harm, hate, harassment, or illegal activities
* Creating content that is intended to deceive, mislead, or scam others
* Creating content that is intended to harm or abuse others

This list is not exhaustive. Pixelcut reserves the right to determine what constitutes prohibited use at its sole discretion and may update this policy at any time.
See the full terms for more details.

### Enforcement

Depending on severity, Pixelcut may take the following actions:

* Block specific requests
* Suspend or terminate account
* Require additional verification for continued access

<Card title="Acceptable use / content policy" icon="shield-halved" href="/developer-guide/resources/faq#can-i-use-the-api-for-commercial-purposes" />


# Data & Privacy 
Source: https://pixelcut.ai/docs/developer-guide/resources/data-privacy

How images are handled, retained, and used.

## Do you store images?

Pixelcut retains images long enough to process requests and deliver results.

* Both input and output images are automatically deleted within 24 hours of being processed.
* Result URLs are temporary and assets are valid for a short period (commonly \~1 hour).

## Who can access my data?

* Only you can access your data.
* Pixelcut does not share your data with third parties except as required by law or to provide the service (e.g., using third-party infrastructure providers).
* Pixelcut employees may only access your data to provide support or to investigate abuse.

## Is my data used for training?

No, Pixelcut does not use your data to train models without your consent.

## What metadata is retained?

Account and usage metadata may be retained for billing, abuse prevention, and analytics.

<CardGroup>
  <Card title="API terms" icon="scale-balanced" href="/developer-guide/resources/api-terms" />

  <Card title="Acceptable use" icon="shield-halved" href="/developer-guide/resources/faq#can-i-use-the-api-for-commercial-purposes" />
</CardGroup>


# Frequently Asked Questions
Source: https://pixelcut.ai/docs/developer-guide/resources/faq

Answers to frequently asked questions about the Pixelcut API.

### General Questions

#### What is the Pixelcut API?

The Pixelcut API allows developers to integrate image editing capabilities into their applications. It supports various operations such as background removal, upscaling, inpainting, and more.

#### Who is Pixelcut API for?

The API is designed for developers and businesses who need to add image editing functionalities to their applications, websites, or services.

#### How do I get started with the Pixelcut API?

You can get started by signing up for an API key on the [dashboard](https://www.pixelcut.ai/developer-settings). Once you have your API key, you can refer to the other pages in this documentation for integration details.

#### Can I use the API for commercial purposes?

Yes, you can use the API for commercial purposes such as creating images for use in a website or application, or providing image editing features in your own software.
You may not use the API to create training data for your own models.

#### Do I retain copyright of the images I process through the API?

Yes, you retain copyright of the images you process through the API.

### Pricing and Billing

#### How is the Pixelcut API priced?

The API operates on a credit subscription model, where each operation consumes a certain number of credits. Credits are available at various plans depending on your needs.

#### Are there any pricing tiers or volume discounts?

No, there are no pricing tiers. For volumes above 1 million credits, please contact us at [api@pixelcut.ai](mailto:api@pixelcut.ai).

#### How do I purchase more credits?

You can purchase additional credits through the [dashboard](https://www.pixelcut.ai/developer-settings).

#### How do I check my remaining credits?

You can check your remaining credits through the [dashboard](https://www.pixelcut.ai/developer-settings) or via the Get Credits endpoint.

#### How are credits consumed?

Credits are consumed based on the operations performed. For example, removing the background from an image consumes 5 credits.
Credits are consumed when the API request is successful. If the API request fails, generally no credits are consumed except in cases where the failure was due to a safety check violation.

### Technical Questions

#### What image formats does the API support?

The API supports JPEG and PNG formats.

#### How do I authenticate API requests?

You need to include your API key in the request header to authenticate API requests, visit [Authentication](/docs/developer-guide/getting-started/authentication-cors) for more information.

#### Is there a limit to the number of API requests I can make at once?

Your developer account is rate limited to 5 requests per second by default.
You can increase this limit by contacting us at [api@pixelcut.ai](mailto:api@pixelcut.ai)

#### How do I handle errors in API responses?

API responses include error codes and messages to help you identify and handle errors. Refer to the documentation for a detailed list of error codes and their meanings.

#### Do your offer SLAs?

We do not offer SLAs for the API at this time. However, these APIs also power the Pixelcut mobile and web products which serve millions of people per month so we aim to have a very reliable service.

### Data and Privacy

#### What data is collected?

We collect two types of data:

1. Account related data such as your email, subscription information, and usage data for billing and analytics purposes.
2. API request data such as the images you process through the API.

#### How long is my data retained?

Images processed through the API are temporarily stored to ensure the operation of the API and are automatically deleted after 1 hour.
Metadata and usage data are retained for billing and analytics purposes.

#### Do you share my data with third parties?

No, we do not share your data with third parties except as required by law or to provide the service (e.g., using third-party infrastructure providers).

#### Can I request the deletion of my data?

Yes, you can request the deletion of your data by contacting our support team. Please note that some data may be retained as required by law or for legitimate business purposes.

#### Will my data be used for training?

No, we do not use your data for training without your consent.

### Support and Troubleshooting

#### How do I contact support for the Pixelcut API?

You can contact our support team via email at [api@pixelcut.ai](mailto:api@pixelcut.ai).

#### What should I do if I encounter an issue with the API?

If you encounter an issue, check the API documentation and FAQs first.
If the issue persists, contact our support team with details of the problem at [api@pixelcut.ai](mailto:api@pixelcut.ai).


# Status Page
Source: https://pixelcut.ai/docs/developer-guide/resources/status-page

Where to look when requests fail or latencies spike.

## API Status Page

The [API status page](https://status.pixelcut.ai/) is regularly updated to reflect any ongoing issues with the API. It is also where any planned maintenance will be announced.

## How to troubleshoot API failures

### First: identify the failure class

* `401 invalid_auth_token`: key missing/incorrect
* `403 insufficient_api_credits`: out of credits
* `429 rate_limit_exceeded`: too much concurrency
* `5xx`: transient server error (retryable)

### If you suspect an incident

* Capture a timestamp, endpoint, and response body (remove secrets)
* Email `api@pixelcut.ai` with the details

### Self-checks

* Verify your API key and environment variables
* Confirm your retry policy isn’t amplifying load during 429s
* Check your credit balance (`GET /v1/credits`)

<CardGroup>
  <Card title="Rate limits & retries" icon="timer" href="/developer-guide/core-concepts/rate-limits" />
</CardGroup>