---
title: "Create a reference set"
method: POST
path: "/v1/workspaces/{workspace_id}/reference-sets"
tags: ["Training"]
---

# Create a reference set

`POST /v1/workspaces/{workspace_id}/reference-sets`

Create a reference set (a curated collection of already-uploaded files) that can then be trained into a custom style/LoRA. Upload files first via the Files API, then pass their IDs here.

## Path parameters

- `workspace_id` string, uuid, required — Id of the workspace that owns the resource.

## Headers

- `Idempotency-Key` string

## Request body

- CreateReferenceSetRequest
  - `name` string, required — Display name for the reference set.
  - `category` 'general' | 'character' | 'object' | 'scene' | 'effect', required — Training category: general (overall aesthetic), character (person/creature), object (specific item), scene (environment), or effect (visual effect).
  - `file_ids` string[], required — Ordered image or video file IDs to include. Must belong to the workspace.
  - `description` string, nullable — Optional description.
  - `cover_file_ids` string[], nullable — Optional ordered image file IDs to show as cover thumbnails. Omit to auto-pick.

## Response `201`

Successful Response

- CreateReferenceSetResponse
  - `reference_set_id` string, uuid, required — ID of the created reference set (train this with a training run).
  - `name` string, required
  - `asset_count` integer, required — Number of input files added to the reference set.
  - `cover_count` integer, required — Number of cover thumbnails set on the reference set.
  - `skipped` SkippedFile[] — Files from file_ids that were not included, each with the reason.
    - `file_id` string, uuid, required
    - `reason` 'not_found' | 'foreign_workspace' | 'already_member' | 'duplicate_in_request', required — Why this file_id was not added: not_found (no such file), foreign_workspace (belongs to another workspace), already_member (already in the set), or duplicate_in_request (listed more than once in this call).

## Other responses

- `401` — Unauthenticated — missing or invalid Bearer token.
- `403` — Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.
- `404` — Resource not found.
- `409` — The request with this `Idempotency-Key` is still running — retry after the number of seconds in `Retry-After`.
- `422` — Invalid input parameters, or an `Idempotency-Key` reused for a different request.
- `429` — Rate limited — retry after the number of seconds in `Retry-After`.
- `500` — Internal server error.

---

[API](https://skmtc.dev/layer/apis/layer-rest-api.md) · [All operations](https://skmtc.dev/layer/apis/layer-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/layer/layer-rest-api/revisions/fafc779f9ba2/schema)