# How to Upload Local Assets and Mockups to Stitch Projects: Complete Guide

> Learn how to upload local assets and mockups to Stitch projects easily. Bypass token limits and send large files directly to Stitch using the stitch::upload-to-stitch skill.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-12

---

**Use the `stitch::upload-to-stitch` skill to invoke a Python script that Base64-encodes local files and transmits them directly to the Stitch `BatchCreateScreens` REST endpoint, bypassing the model's ~16K token output limit that would otherwise truncate large assets.**

The `stitch::upload-to-stitch` skill provides the canonical method to upload local assets and mockups to Stitch projects within the `google-labs-code/stitch-skills` ecosystem. This tool handles images, HTML mockups, and design markdown files by delegating the heavy lifting to a dedicated Python helper rather than attempting to process file contents through model outputs. By calling the Stitch API directly, the skill ensures reliable uploads regardless of file size, integrating seamlessly with the broader design system pipeline.

## Why Direct API Upload Matters

Model outputs are constrained to approximately 16,000 tokens, while even modest PNG files require over 70,000 characters when Base64-encoded. The [`upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py) script located at [`plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py) solves this bottleneck by executing the upload outside the model context. It reads the local file, encodes it to Base64, and POSTs the payload to the Stitch `BatchCreateScreens` endpoint at `https://stitch.googleapis.com/v1/projects/<projectId>/screens:batchCreate`.

## Prerequisites for Uploading Local Assets

Before executing an upload, you must complete three preparation stages:

1. **Locate the target project** – Use the `list_projects` tool to retrieve the `projectId` of the Stitch project you want to augment.
2. **Obtain a valid API key** – The script requires an `X-Goog-Api-Key` header value. Extract this from MCP configuration files such as [`.gemini/antigravity/mcp_config.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.gemini/antigravity/mcp_config.json), `~/.gemini/settings.json`, or `~/.claude.json` as listed in the skill documentation. If the key is unavailable, prompt the user to supply it manually.
3. **Verify file accessibility** – Ensure the target file exists at the specified local path and is readable by the script.

## Technical Implementation of the Upload Script

The Python utility implements a three-stage pipeline to transform local files into Stitch screens.

### MIME Type Detection

The script maps file extensions to MIME types using the `_MIME_TYPES` dictionary (lines 48-57 of [`upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py)). This mapping determines whether the upload becomes a `DOCUMENT` screen (HTML/Markdown) or an `IMAGE` screen (PNG, JPG, etc.).

### Screen Request Construction

The `build_screen_request` function (lines 29-77) constructs the `CreateScreenRequest` payload. For HTML and Markdown uploads, it adds optional `title` and `generatedBy` metadata fields to track the source of the design asset.

### API Execution

The `call_batch_create_screens` function (lines 66-94) handles the HTTP POST to the Stitch API. It includes the Base64-encoded file data and respects the optional `createScreenInstances` flag to generate displayable screen instances immediately upon upload.

## Uploading Assets to Stitch Projects

Execute the script using the command template defined in [`plugins/stitch-design/skills/upload-to-stitch/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/upload-to-stitch/SKILL.md). The CLI requires `--project-id`, `--file-path`, and `--api-key` parameters, with optional `--title` or `--generated-by` flags for metadata.

### Upload a PNG Screenshot

```bash
python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path ./assets/homepage.png \
  --api-key AIzaSyExampleKey \
  --title "Homepage Screenshot"

```

### Upload an HTML Mockup

```bash
python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path ./mockups/checkout.html \
  --api-key AIzaSyExampleKey \
  --generated-by "stitch::extract-static-html"

```

### Upload a Design Markdown File

```bash
python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
  --project-id 1234567890 \
  --file-path .stitch/DESIGN.md \
  --api-key AIzaSyExampleKey \
  --title "App Design System"

```

## SSL Certificate Configuration

The script attempts to load the system CA bundle via the `certifi` Python package. On macOS or systems with custom certificate stores, set the `SSL_CERT_FILE` environment variable manually to point to your certificate authority bundle if the default resolution fails.

## Summary

- The `stitch::upload-to-stitch` skill uses [`upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py) to bypass model token limits by calling the Stitch API directly.
- Files are Base64-encoded and sent to the `BatchCreateScreens` endpoint at `https://stitch.googleapis.com/v1/projects/<projectId>/screens:batchCreate`.
- The script auto-detects MIME types via the `_MIME_TYPES` dictionary (lines 48-57) to create either `IMAGE` or `DOCUMENT` screens.
- The `build_screen_request` function (lines 29-77) handles payload construction, while `call_batch_create_screens` (lines 66-94) executes the HTTP POST.
- Required parameters include `projectId`, `file-path`, and `X-Goog-Api-Key` extracted from MCP configuration files.

## Frequently Asked Questions

### What file types can I upload to Stitch projects?

The script supports images (PNG, JPEG) that become `IMAGE` screens, and HTML or Markdown files that become `DOCUMENT` screens. The MIME type is automatically detected from the file extension using the `_MIME_TYPES` mapping defined at lines 48-57 of [`upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py).

### Why can't I paste Base64 data directly into the model?

Model outputs are limited to approximately 16,000 tokens, while Base64-encoded images often exceed 70,000 characters. The Python script bypasses this limitation by executing the upload outside the model context and calling the Stitch REST API directly via the `call_batch_create_screens` function.

### Where do I find the Stitch API key?

The `X-Goog-Api-Key` is stored in MCP configuration files such as [`.gemini/antigravity/mcp_config.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.gemini/antigravity/mcp_config.json), `~/.gemini/settings.json`, or `~/.claude.json`. If the script cannot locate these files, you must provide the key manually via the `--api-key` parameter.

### How does the script handle different screen types?

The `build_screen_request` function (lines 29-77) inspects the MIME type to determine screen classification. HTML and Markdown files receive `DOCUMENT` typing with optional `title` and `generatedBy` metadata, while images receive `IMAGE` typing, all configured in the `CreateScreenRequest` payload sent to the `BatchCreateScreens` endpoint.