Records & libraries

Create a moodboard

Analyse 10 to 60 images into a moodboard — its palette, fabrics, prints, key items and keywords — delivered as a moodboard: record you can read, and pass to generation.

Endpoint: POST https://api.refabric.com/v1/tasks/moodboard.createTask: moodboard.createScope: tasks:runCategory: Records & libraries

Quick start

import os
import time
import requests

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

job = requests.post(
    "https://api.refabric.com/v1/tasks/moodboard.create",
    headers=headers,
    json={
        "images": [
            "https://example.com/looks/1.jpg",
            "https://example.com/looks/2.jpg",
            "https://example.com/looks/3.jpg",
            "https://example.com/looks/4.jpg",
            "https://example.com/looks/5.jpg",
            "https://example.com/looks/6.jpg",
            "https://example.com/looks/7.jpg",
            "https://example.com/looks/8.jpg",
            "https://example.com/looks/9.jpg",
            "art:9f3c01",
        ],
    },
).json()
print(job["job_id"])

while True:
    status = requests.get(job["status_url"], headers=headers).json()
    if status["lifecycle"] == "terminal":
        break
    time.sleep(5)

print(requests.get(job["result_url"], headers=headers).json())

cURL waits for the result with Prefer: wait; when the job outlives the wait, it answers 202 with the job's URLs.

Input schema

array<string>required
10 to 60 images to analyse, each one string. Every image is analysed as a look. An image that cannot be read is left out of the board and named in the job's summary.warnings (image_not_fetchable); it is still charged, as the price is set by the number of images sent.
at least 10 items · at most 60 items
Example: ["https://example.com/looks/1.jpg","https://example.com/looks/2.jpg","https://example.com/looks/3.jpg","https://example.com/looks/4.jpg","https://example.com/looks/5.jpg","https://example.com/looks/6.jpg","https://example.com/looks/7.jpg","https://example.com/looks/8.jpg","https://example.com/looks/9.jpg","art:9f3c01"]
stringoptional
The moodboard's name, as it appears in your moodboard list. Omitted: "Untitled Moodboard".
Example: SS27 resort
array<object>optional
Optional: your own fabrics and prints, each {type, url, name}, up to 60 of each type — the same shape as a moodboard's data.items. Sending any item of a type REPLACES that section of the analysis: the board's fabrics (or prints) are then exactly yours, not analysed, with no swatch made. Send none of a type to have it found in the images.
at most 120 items
Example: [{"type":"fabric","url":"https://files.example.com/moodboard.create/1.jpg","name":"washed linen"},{"type":"print","url":"https://files.example.com/moodboard.create/2.png"}]
- stringrequired
  What one part (items[]) of a record is.
  Values
  fabric — A fabric: its swatch or a photo of it. When the image is a fabric swatch or a photo of a fabric.
  print — A print or pattern. When the image is a print or pattern.
  Example: fabric
- stringrequired
  Any image, as one string: a URL, a file from an earlier result (art:… or its url), an upload (file:…) or a part of a record (an items[].url of its data).
  pattern: ^(https://|art:|file:).+$
  Example: https://files.example.com/moodboard.create/1.jpg
- stringoptional
  The item's name, shown on the board. Omitted: your library label for that image, when it has one.
  max length 80
  Example: washed linen
array<object>optional
Optional: up to 10 colours of your own, each {hex} (a colour from a moodboard's data.colours may be sent as it is). The colours you send become the palette later tasks use; the file's colours show the palette read from the images.
at most 10 items
Example: [{"hex":"#E8D9C4"},{"hex":"#2F4A3A"}]
- stringrequired
  The colour as #RRGGBB, like "#E8D9C4".
  pattern: ^#[0-9A-Fa-f]{6}$
- stringoptional
  A name for the colour.
- stringoptional
  Its Pantone code, when known.
stringoptionalDefault: trend
What kind of moodboard to make from the images. A trend board reads every image as a look — its palette, fabrics, prints, key items and keywords — which is what most boards are made for, and it takes your own fabrics, prints and colours.
Values
- trend — A trend moodboard: each look is captioned and analysed into its palette, fabrics, prints, key items and keywords. You may send your own fabrics, prints and colours.
- brand_dna — A brand DNA moodboard: what the images say about one brand's recurring style. Best on a brand's own lookbook. Takes no items or colours. When the images are one brand's own lookbook and you want its recurring style.
Example: trend

Output schema

array<object>optional
One file: the moodboard record, moodboard:<id> — the same line GET /v1/files/moodboard:<id> answers, its url the cover and its data the record (name · description · status · colours · items · keywords). Pass the handle to image.generate in moodboards.
objectoptional
How many images were sent and analysed, and which could not be read.
- integeroptional
  Images sent (and charged).
- integeroptional
  Images on the board that came back analysed.
- array<object>optional
  One {code, field, message} per image that could not be read (code: "image_not_fetchable", field: "images[i]"). Such an image is not on the board and is still charged.

Required-fields example

{
  "images": [
    "https://example.com/looks/1.jpg",
    "https://example.com/looks/2.jpg",
    "https://example.com/looks/3.jpg",
    "https://example.com/looks/4.jpg",
    "https://example.com/looks/5.jpg",
    "https://example.com/looks/6.jpg",
    "https://example.com/looks/7.jpg",
    "https://example.com/looks/8.jpg",
    "https://example.com/looks/9.jpg",
    "art:9f3c01"
  ]
}

Full example

{
  "kind": "trend",
  "name": "SS27 resort",
  "images": [
    "https://example.com/looks/1.jpg",
    "https://example.com/looks/2.jpg",
    "https://example.com/looks/3.jpg",
    "https://example.com/looks/4.jpg",
    "https://example.com/looks/5.jpg",
    "https://example.com/looks/6.jpg",
    "https://example.com/looks/7.jpg",
    "https://example.com/looks/8.jpg",
    "https://example.com/looks/9.jpg",
    "art:9f3c01"
  ],
  "items": [
    {
      "type": "fabric",
      "url": "https://files.example.com/moodboard.create/1.jpg",
      "name": "washed linen"
    },
    {
      "type": "print",
      "url": "https://files.example.com/moodboard.create/2.png"
    }
  ],
  "colours": [
    {
      "hex": "#E8D9C4"
    },
    {
      "hex": "#2F4A3A"
    }
  ]
}

Response example

{
  "job_id": "5b3d2e22a29942faa12752c7f1e5673d",
  "lifecycle": "queued",
  "status_url": "http://v3-api.refabric.com/v1/jobs/5b3d2e22a29942faa12752c7f1e5673d",
  "result_url": "http://v3-api.refabric.com/v1/jobs/5b3d2e22a29942faa12752c7f1e5673d/result",
  "cancel_url": "http://v3-api.refabric.com/v1/jobs/5b3d2e22a29942faa12752c7f1e5673d/cancel"
}

Result example

{
  "job_id": "5b3d2e22a29942faa12752c7f1e5673d",
  "files": [
    {
      "file": "moodboard:5b3d2e22-a299-42fa-a127-52c7f1e5673d",
      "url": "https://files.example.com/moodboard.create/3.jpg",
      "media_type": "application/json",
      "task": "moodboard.create",
      "job_id": "5b3d2e22a29942faa12752c7f1e5673d",
      "created_at": "2026-09-30T10:02:11Z",
      "data": {
        "name": "SS27 resort",
        "description": "Sun-bleached neutrals and relaxed tailoring for a coastal resort season.",
        "status": "ready",
        "colours": [
          {
            "hex": "#E6D8C3",
            "name": "Sandshell",
            "pantone": "13-1106 TCX"
          }
        ],
        "items": [
          {
            "type": "fabric",
            "name": "washed linen",
            "url": "https://files.example.com/moodboard.create/1.jpg"
          },
          {
            "type": "print",
            "url": "https://files.example.com/moodboard.create/2.png"
          },
          {
            "type": "look",
            "url": "https://files.example.com/moodboard.create/3.jpg"
          }
        ],
        "keywords": [
          "resort",
          "relaxed tailoring",
          "linen"
        ]
      }
    }
  ],
  "has_more": false,
  "summary": {
    "requested": 10,
    "delivered": 9,
    "warnings": [
      {
        "code": "image_not_fetchable",
        "field": "images[4]",
        "message": "This image could not be read and is not on the board. It is still charged: the price is set by the number of images sent."
      }
    ]
  }
}

A kind: trend moodboard. The two items become the board's fabric and print sections, and the colours you send become the palette later tasks use; data.colours shows the palette read from the images.

Send the images that set a direction — runway looks, a lookbook, your own photos — and get one moodboard back: the palette, the fabrics and prints found in the images, the key items and keywords. Pass it to generation and new designs follow it.

Built for

Trend research from runway and street images
A collection's direction, before design starts
A brand's own look, from its lookbook (kind: brand_dna)

What you get

One moodboard: record — its name, description, status and keywords.
The palette in data.colours and the fabrics, prints and key items found in the images in data.items.
A cover image as the record's url, and a summary that counts the images used and names any that could not be read.

Specs

Input formats	Images, each one string: a URL, an upload (`file:…`) or a file from an earlier result (`art:…`). Upload types and sizes: `GET /v1/meta` `limits.upload`.
Input count	`images`: 10 to 60; `items`: up to 120, each with its image
Output format	One `moodboard:` record: its `data` is JSON in the record vocabulary, its `url` a preview image.
Outputs per job	One record file, however many images you send.

Choosing a task

Use this when you want a direction read from images: what they share in colour, fabric, print and items. Use brand_kit.create when you want your own colours and images kept as they are, for generation to use.

Errors

image.generate · It runs after: it takes this task's result.
range_plan.create · It runs after: it takes this task's result.
brand_kit.create · It does a neighbouring job.

Good to know

images holds at least 10 items.
images holds at most 60 items.
items holds at most 120 items.
items[].name is at most 80 characters.
colours holds at most 10 items.
items is taken only with kind: trend.
colours is taken only with kind: trend.

Pricing: Estimate a request before you run it, or see the price of each option.

For agents and code generation

https://api.refabric.com/v1/tasks/moodboard.create/llms.txt
https://api.refabric.com/v1/tasks/moodboard.create/openapi.json
GET https://api.refabric.com/v1/tasks/moodboard.create

Schema changes follow Versioning.