Generate designs

Endpoint: POST https://api.refabric.com/v1/tasks/image.generateTask: image.generateScope: tasks:runCategory: Design generation

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/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())

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

Input schema

• promptstringrequired

  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

• resolutionstringoptionalDefault: 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_ratiostringoptional

  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_countintegeroptionalDefault: 1

  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.

  1 to 40

  Example: 2

• referencesarray<object>optional

  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.

  at most 14 items

  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"}]

  Show child attributes
• moodboardsarray<string>optional

  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.

  at most 1 items

• brand_kitstringoptional

  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).

  pattern: ^brand_kit:[0-9]+$

Output schema

• filesarray<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.

• summaryobjectoptional

  How many designs came back. It can be fewer than image_count: one that fails is left out and not charged.

  Show child attributes

Required-fields example

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

Full example

{
  "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
}

Response example

{
  "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

{
  "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.

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.

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

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.

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/image.generate/llms.txt
• https://api.refabric.com/v1/tasks/image.generate/openapi.json
• GET https://api.refabric.com/v1/tasks/image.generate