# Generate designs

> Create new fashion designs from a prompt, reference images, a moodboard or a brand kit. Each design is delivered as an image file you can edit or reuse.

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

Describe a garment in words, or design from your own pictures, a moodboard or a brand kit, and get finished design images back. With references you say what each picture gives the design — the garment to build on, its fabric, its print, its style — and how closely to follow it. With a moodboard or a brand kit, the design draws on what in it fits your prompt.

## 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/image.generate",
    headers=headers,
    json={
        "prompt": "a relaxed linen shirt dress for resort, midi length",
    },
).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/image.generate", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "a relaxed linen shirt dress for resort, midi length"
  }),
}).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/image.generate" \
  -H "Authorization: Key $REFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"prompt":"a relaxed linen shirt dress for resort, midi length"}'
```

## Input schema

- `prompt` (string, _required_) — What to design. Required, except that it may be empty ("") when you send references and no moodboard or brand kit.
  Example: `a relaxed linen shirt dress for resort, midi length`
- `resolution` (string, _optional_, default: `2K`) — How large the result 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`
- `aspect_ratio` (string, _optional_) — The shape of the result, as width:height. `auto` keeps the shape of the reference the design is built on, and makes a portrait 9:16 design when there is none to keep — from words alone, from references used only as inspiration, or from a moodboard or a brand kit. Send nothing and a design built on your references keeps the shape of the one it is built on (portrait 9:16 when they are only inspiration), while a design from words alone, a moodboard or a brand kit comes out square 1:1 — a neutral shape when there is no picture to follow. Send `auto` to get portrait 9:16 there instead, or name the ratio you need.
  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: `3:4`
- `image_count` (integer, _optional_, default: `1`, 1 to 40) — How many designs to make, 1–40. Each delivered design is charged; one that fails is not. One, so you see a first result before you ask for more. Higher makes more independent designs in one job, each from the same request.
  Example: `2`
- `references` (array<object>, _optional_, at most 14 items) — Up to 14 reference images, each {image, use_case, note, fidelity}. To design from a look of your brand kit, send the look's URL (from the kit's `data`) with `use_case: "frame"` and name the kit in `brand_kit`: that look becomes the base of the design. Without `brand_kit` the same image is a plain reference.
  Example: `[{"image":"https://files.example.com/image.generate/1.jpg","use_case":"garment","note":"the collar only","fidelity":70},{"image":"fabric:0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d","use_case":"fabric"}]`
  - `image` (string, _required_, pattern: ^(https://|art:|file:|fabric:).+$) — Any image, as one string: a URL, a file from an earlier result (`art:…` or its url), an upload (`file:…`), a part of a record (an `items[].url` of its `data`), or a library fabric (`fabric:<fabric_id>`). The fabric's swatch and facts (weight, pattern, type, composition) shape the design, in the fabric's base colour. With a moodboard or a brand kit a fabric acts as a plain picture.
    Example: `https://files.example.com/image.generate/1.jpg`
  - `use_case` (string, _optional_, default: `auto`) — What to take from this image; with `auto` the use is chosen for you. `frame` means: base the design on this image (with `brand_kit`, a look of that kit).
    Values: `auto` (The use is chosen for you.); `garment` (Use this garment as the base: its shape, cut and construction. When the design should be built on the garment this image shows.); `fabric` (Use this exact fabric: its material, texture and weave. When the design must use exactly this fabric.); `sketch` (Treat this image as a sketch or line drawing to turn into a design. When the image is a drawing to turn into a finished design.); `style` (Take general style inspiration from it, without copying details. When you want the image's look and feel, not its details.); `print` (Use this print or pattern. When the design must carry this print or pattern.); `colour` (Use its colours. When you want only the image's colours.); `pose` (Use the pose of the person in it. When the result should take the pose of the person in the image.); `background` (Use it as the background or setting. When the result should be set in this image's place or backdrop.); `inspiration` (Loose inspiration: mood and feel rather than any one element. When the image is a loose mood reference.); `trend` (Treat it as a trend reference to follow. When the image shows a trend the design should follow.); `frame` (Treat it as the image being edited, not a reference beside it. When this image is the one to edit, or a brand kit's look to start the design from.)
    Example: `garment`
  - `note` (string, _optional_) — Optional words about this reference, such as "the collar only".
    Example: `the collar only`
  - `fidelity` (integer, _optional_, default: `50`, 0 to 100) — How closely to follow this reference: 0–33 follows its style, 34–66 also its materials, 67–100 also its construction.
    Example: `70`
- `moodboards` (array<string>, _optional_, at most 1 items) — At most one moodboard to design from, as ["moodboard:<id>"]: one of yours (`GET /v1/refs/moodboard`) or a curated one (`GET /v1/refs/moodboard?curated=true`). Brand-DNA and trend moodboards both work; the board must have finished its analysis. The design draws on what in the board fits your prompt.
- `brand_kit` (string, _optional_, pattern: ^brand_kit:[0-9]+$) — A brand kit to design from, as "brand_kit:<id>" (`GET /v1/refs/brand_kit`). Every item of the kit informs the design and its colours bound the palette. Its looks are passed in `references` (see there).

## Required-fields example

```json
{
  "prompt": "a relaxed linen shirt dress for resort, midi length"
}
```

## Full example

```json
{
  "prompt": "a relaxed linen shirt dress for resort, midi length",
  "references": [
    {
      "image": "https://files.example.com/image.generate/1.jpg",
      "use_case": "garment",
      "note": "the collar only",
      "fidelity": 70
    },
    {
      "image": "fabric:0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "use_case": "fabric"
    }
  ],
  "resolution": "2K",
  "aspect_ratio": "3:4",
  "image_count": 2
}
```

## Output schema

- `files` (array<object>, _optional_) — One `design` image (`image/*`) per delivered design, each on a new design record. Pass one back as a reference to continue from it.
- `summary` (object, _optional_) — How many designs came back. It can be fewer than `image_count`: one that fails is left out and not charged.
  - `delivered` (integer, _optional_) — How many designs 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:9f3c01",
      "url": "https://files.example.com/image.generate/2.png",
      "media_type": "image/png",
      "task": "image.generate",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-09-29T10:02:11Z"
    },
    {
      "file": "art:9f3c02",
      "url": "https://files.example.com/image.generate/3.png",
      "media_type": "image/png",
      "task": "image.generate",
      "job_id": "5f0c2a1e9b8d4c7a8e6f1d2c3b4a5968",
      "created_at": "2026-09-29T10:02:14Z"
    }
  ],
  "has_more": false,
  "summary": {
    "delivered": 2
  }
}
```

Made from the references alone (no moodboard or brand kit): the garment reference gives the collar, the library fabric gives the material.

## Built for

- New styles from a written idea
- Designs built on your own sketches, photos or swatches
- A collection that follows a moodboard or a brand kit

## What you get

- One design image per delivered design, each saved as a new design you can open, edit or pass back as a reference.
- A `summary` whose `delivered` counts the designs 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 design, up to `image_count`.

## Choosing a task

- Use this when you want a garment design. Use `pattern.generate` when you want a flat textile repeat to use as a print.

## Errors

- `field_not_accepted`
- `invalid_option`
- `invalid_request`
- `prompt_required`
- `too_many_references`
- `not_found`
- `moodboard_not_ready`
- `brand_kit_look_not_ready`
- `insufficient_credits`
- `content_refused`
- `processing_failed`

## Related

- `moodboard.create` — It runs before: its result is this input.
- `brand_kit.create` — It runs before: its result is this input.
- `image.upscale` — It runs after: it takes this task's result.
- `image.extract_materials` — 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.
- `moodboards` holds at most 1 items.

## For agents and code generation

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