---
title: "Add a reference image"
method: POST
path: "/v1/collections/{id}/references"
tags: ["References"]
deprecated: true
---

# Add a reference image

`POST /v1/collections/{id}/references`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/collections/{id}/references`
- Auth: HTTP bearer

> **Deprecated.**

Adds an image as a collection-scoped style reference (up to 6 references). Pass either `url` to download and store a new reference, or `asset_id` to copy an existing uploaded/generated image into this collection when needed. The returned `reference_asset_ids` are always collection-scoped assets that the app can display and future generations can use. Invalidates the cached style_card, which will be re-extracted on next generation. No credit cost.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- AddReferenceBody
  - `asset_id` string, uuid: Asset ID of an existing uploaded or generated image. If the asset is not already scoped to this collection, the API creates a collection-scoped reference copy and stores that copied asset ID in reference_asset_ids.
  - `url` string, uri: Public HTTP(S) image URL, up to 10 MB with a 15-second download deadline. Private addresses and unsafe redirects are rejected. PNG, JPEG, WebP, GIF and SVG are supported; SVG is converted to PNG. Downloaded and stored as a collection-scoped reference asset.

## Response `201`

Reference added

- ReferenceResponse
  - `data` ReferenceData, required
    - `reference_asset_ids` string[], required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/84832e255613?raw)