# Generate textile patterns

> Create textile repeats from a prompt and optional reference images. Each pattern is delivered as an image file you can reuse as a print.

**Endpoint:** `POST https://api.refabric.com/v1/tasks/pattern.generate` · **Task:** `pattern.generate` · **Scope:** `tasks:run` · **Category:** Design generation

Describe a print — its motif, scale, colours and style — and get textile repeats back. Add reference pictures such as a print photo, a swatch or an extracted print, and set on the first one how closely every repeat follows them. Each repeat is saved as a new design you can pass on as a print.

## Quick start

```python
import os
import time
import requests

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

job = requests.post(
    "https://api.refabric.com/v1/tasks/pattern.generate",
    headers=headers,
    json={
        "prompt": "small tossed florals on a deep navy ground, two-colour",
    },
).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())
```

```javascript
const headers = {
  Authorization: `Key ${process.env.REFABRIC_API_KEY}`,
  "Content-Type": "application/json",
};

const job = await fetch("https://api.refabric.com/v1/tasks/pattern.generate", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "small tossed florals on a deep navy ground, two-colour"
  }),
}).then((r) => r.json());
console.log(job.job_id);

let status = job;
while (status.lifecycle !== "terminal") {
  await new Promise((r) => setTimeout(r, 5000));
  status = await fetch(job.status_url, { headers }).then((r) => r.json());
}

console.log(await fetch(job.result_url, { headers }).then((r) => r.json()));
```

```bash
curl -X POST "https://api.refabric.com/v1/tasks/pattern.generate" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"prompt":"small tossed florals on a deep navy ground, two-colour"}'
```

## Input schema

- `prompt` (string, _required_) — What the repeat should show — motif, scale, colours, style. Required, also with references.
  Example: `small tossed florals on a deep navy ground, two-colour`
- `resolution` (string, _optional_, default: `2K`) — How large each repeat is. `2K` is sharp enough for screens and review; ask for `4K` when the result will be printed or zoomed into.
  Values: `2K` (Standard size, for screens and review.); `4K` (Large size, for print and zoom. When the image will be printed or zoomed into.)
  Example: `2K`
- `image_count` (integer, _optional_, default: `1`, 1 to 40) — How many repeats to make, 1–40. Each delivered repeat is charged; one that fails is not. One, so you see a first result before you ask for more. Higher makes more independent repeats in one job, each from the same request.
  Example: `2`
- `references` (array<object>, _optional_, at most 14 items) — Up to 14 images to base the repeat on, each {image, fidelity}: a print photo, a swatch, an `image.extract_print` result or any earlier file. The whole pattern follows ONE fidelity, the first reference's; a `fidelity` on a later reference is refused.
  Example: `[{"image":"art:a1b2c5","fidelity":70},{"image":"https://files.example.com/pattern.generate/1.jpg"}]`
  - `image` (string, _required_, pattern: ^(https://|art:|file:).+$) — A picture, as one string: a URL, a file from an earlier result (`art:…`, or its `url`) or an upload (`file:…`).
    Example: `art:a1b2c5`
  - `fidelity` (integer, _optional_, 0 to 100) — How closely the repeat follows the references — set on the FIRST reference; it applies to all of them. 0–33 follows their motif, 34–66 uses them as a loose visual guide, 67–100 keeps their motifs and layout. Not set on the first reference, 50.
    Example: `70`
- `aspect_ratio` (string, _optional_, default: `auto`) — The shape of the repeat, as width:height. `auto` follows the first reference's shape; with no reference a suitable shape is chosen. `auto` lets your first reference set the repeat's shape, so a print photo or swatch keeps its proportions; with no reference the shape is chosen for you. Name a ratio when the repeat must fit a fixed shape.
  Values: `auto` (Keep the shape of the input image; with none, a suitable shape is chosen.); `1:1` (Square. For square places: product grids and social posts.); `3:4` (Portrait, slightly taller than wide. For portrait product pages.); `4:3` (Landscape, slightly wider than tall. For landscape layouts and slides.); `9:16` (Tall portrait, as for phone screens and stories. For phone screens: stories and reels.); `16:9` (Wide landscape, as for banners and video. For banners, headers and video frames.); `2:3` (Portrait, as for a classic photo print. For a portrait print or a lookbook page.); `3:2` (Landscape, as for a classic photo print. For a landscape print.); `4:5` (Portrait, as for social feeds. For portrait posts in social feeds.)
  Example: `1:1`

## Required-fields example

```json
{
  "prompt": "small tossed florals on a deep navy ground, two-colour"
}
```

## Full example

```json
{
  "prompt": "small tossed florals on a deep navy ground, two-colour",
  "references": [
    {
      "image": "art:a1b2c5",
      "fidelity": 70
    },
    {
      "image": "https://files.example.com/pattern.generate/1.jpg"
    }
  ],
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "image_count": 2
}
```

## Output schema

- `files` (array<object>, _optional_) — One repeat image (`image/*`) per delivered pattern, each on a new design record. Pass one on as a reference (`image.generate` with `use_case: "print"`) or to an edit.
- `summary` (object, _optional_) — How many repeats came back. It can be fewer than `image_count`: one that fails is left out and not charged.
  - `delivered` (integer, _optional_) — How many repeats were delivered (and charged).

## Response example

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

## Result example

```json
{
  "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
  "files": [
    {
      "file": "art:7c1e01",
      "url": "https://files.example.com/pattern.generate/2.png",
      "media_type": "image/png",
      "task": "pattern.generate",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-10-01T10:02:11Z"
    },
    {
      "file": "art:7c1e02",
      "url": "https://files.example.com/pattern.generate/3.png",
      "media_type": "image/png",
      "task": "pattern.generate",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-10-01T10:02:12Z"
    }
  ],
  "has_more": false,
  "summary": {
    "delivered": 2
  }
}
```

The first reference's fidelity (70) applies to both references: their motifs and layout are kept. `aspect_ratio` is left out, so the repeat takes the first reference's shape. Each repeat is saved as a new design.

## Built for

- Prints for a new collection
- A repeat built from a print photo or a swatch
- Prints to apply to your garment designs

## What you get

- One repeat image per delivered pattern, each saved as a new design.
- A `summary` whose `delivered` counts the repeats that came back — the ones charged.

## 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:** `references`: up to 14, each with its image
- **Output format:** Files: each one line with its `url` and its `media_type`, in the job's result.
- **Output resolution:** `2K`, `4K`
- **Aspect ratios:** `auto`, `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `4:5`
- **Outputs per job:** One file per delivered repeat, up to `image_count`.

## Choosing a task

- Use this when you want a new repeat made from a description and references. Use `image.extract_print` when you want the print of an existing garment lifted out as it is, as a flat sample rather than a repeat.

## Errors

- `field_not_accepted`
- `invalid_option`
- `invalid_request`
- `prompt_required`
- `too_many_references`
- `not_found`
- `field_not_supported`
- `insufficient_credits`
- `content_refused`
- `processing_failed`

## Related

- `image.extract_print` — It runs before: its result is this input.
- `image.generate` — It runs after: it takes this task's result.
- `image.upscale` — It runs after: it takes this task's result.

## Good to know

- `image_count` is from 1 to 40.
- `references` holds at most 14 items.
- `references[].fidelity` is from 0 to 100.

## For agents and code generation

- https://api.refabric.com/v1/tasks/pattern.generate/llms.txt
- https://api.refabric.com/v1/tasks/pattern.generate/openapi.json
- GET https://api.refabric.com/v1/tasks/pattern.generate