For AI agents: this page is also available as Markdown at https://docs.refabric.com/task-apis/common-task-arguments.md, and the index of every page is https://docs.refabric.com/llms.txt.
Task APIs
Common task arguments
The inputs that recur across tasks and behave the same way wherever they appear.
Each task defines its own input schema, with its own required fields, defaults and limits — read it
on the task's page in the Task API Reference or at GET /v1/tasks/{name}.
The fields below recur, and they mean the same thing in every task that takes them. Where a range
or a default differs by task, the task's schema is the one that applies. Leaving a field out gives its default; sending the default gives exactly the same result.
prompt
What you want, in your own words. Some tasks require it, some take it as an optional note.
| Type | string |
| Default | per task: required, optional, or allowed to be empty ("") in some cases |
| Range | per task (maxLength in its schema) |
| Cost effect | none |
{ "prompt": "a relaxed linen shirt dress for resort" }An edit task's prompt names one change (image.glam: "make the lipstick red"); a broad sentence
changes more of the image. A video prompt describes movement, since the image already shows what
everything looks like. Each task's field description says what its prompt is for.
Media fields
Every image a task takes — image, images[], references[].image, products[].image — is one
string. There is no object form.
| Type | string |
| Accepted | a public https:// URL · a file from an earlier result (art:…, or the url we gave you) · an upload (file:…) · a part of a record (an items[].url of its data) |
| Also accepted as | some fields take more handles, such as a library fabric (fabric:…) in image.generate references; the field's schema lists them |
| Cost effect | none, except where a task's price depends on where the image was made (Pricing) |
{ "image": "art:x1" }
{ "image": "https://example.com/look.jpg" }Prefer a handle we gave you (art:…, file:…) over a url. A file we produced keeps its context —
what made it and where it belongs — so the next task knows what it is editing; any other image starts
fresh (Files and media).
URLs are https only and must resolve to a public address. Pass a public https URL or an uploaded file
(Limits).
references, use_case and fidelity
references is a list of images that guide a generation. Each item is an object with its image
and, in tasks that take them, what to take from it (use_case) and how closely to follow it
(fidelity).
| Type | array of {image, use_case?, note?, fidelity?} |
| Default | none |
| Range | maxItems per task; fidelity an integer within the bounds in the task's schema |
| Values | use_case: the use_case vocabulary; auto picks the value for you |
| Cost effect | none |
{ "prompt": "a jacket in this fabric",
"references": [ { "image": "file:1234", "use_case": "fabric", "fidelity": 80 } ] }Fidelity is not the same everywhere: in image.generate each reference has its own; in
pattern.generate the first reference's applies to all of them, and a fidelity on a later one is
refused. The concepts are explained at use_case
and on the task pages.
resolution
How large the result is.
| Type | string |
| Default | per task (in its schema, with the reason for it) |
| Values | the resolution vocabulary, which also lists every task that takes it |
| Cost effect | /estimate prices your request |
{ "resolution": "4K" }aspect_ratio
The shape of the result, as width:height.
| Type | string |
| Default | per task |
| Values | the aspect_ratio vocabulary; each task lists the values it takes |
| Cost effect | none |
{ "aspect_ratio": "3:4" }Where a task offers auto, it keeps the shape of the image the result is built on; the task's field
description says what happens when there is none, and what an omitted aspect_ratio means there.
image_count
How many independent results one job makes from the same request.
| Type | integer |
| Default | per task |
| Range | per task (minimum / maximum in its schema) |
| Cost effect | each delivered result is charged; one that fails is not |
{ "prompt": "a navy linen shirt dress", "image_count": 4 }model and models
Who appears in the result, as model:<id> handles listed at GET /v1/refs/model.
| Type | model: string; models: array of strings |
| Default | model: the model the image was shot with; models: none — a shoot needs at least one |
| Values | model:<id> — a base model or one of its styles (GET /v1/refs/model?base=model:<id> lists one model's styles) |
| Cost effect | in a shoot, every product is shown on every model, so each model multiplies the images and the cost |
{ "models": ["model:4412", "model:5501"] }An edit task (model) uses the model an image we made was shot with, whatever you send; send one
only for a picture that carries no such record, such as an upload or a url.
poses
Which poses to make, from the library (pose:<id>, listed at GET /v1/refs/pose) or in words.
| Type | object, chosen by type |
| Values | per task; for example image.repose takes {type: "custom", items: [...]}, each item {type: "library", pose: "pose:<id>"} or {type: "prompt", prompt} |
| Cost effect | every pose made is one image and one charge |
{ "poses": { "type": "custom", "items": [ { "type": "library", "pose": "pose:7c1e" },
{ "type": "prompt", "prompt": "hands in pockets" } ] } }background
The backdrop behind the result, chosen by type.
| Type | object, chosen by type |
| Default | per task |
| Values | per task — the task's schema lists the values it takes (GET /v1/tasks/{name}) |
| Cost effect | /estimate prices each choice |
{ "background": { "type": "library", "background": "background:91aa" } }The same word can do different work in different tasks: in image.change_background the
background is the point of the job, while in a shoot it is the one backdrop behind every image. Each
task's schema lists the values it takes, and says what each one produces there.
views
The product views a shoot makes besides its images on models, one {type, view} each.
| Type | array of {type, view?, reuse?} |
| Default | per task |
| Values | type: the item_type values a shoot can make (ghost, flat, close_up); view: the view_angle vocabulary |
| Cost effect | each made view is an image and a charge; a reused view is not charged again; see /estimate |
{ "views": [ { "type": "ghost", "view": "front" }, { "type": "ghost", "view": "back" }, { "type": "close_up" } ] }category
What a product is. It is not a task input: you set it once when you upload the product
(POST /v1/files), and the shoots read it from the product — how it is worn, framed and restored.
| Type | string |
| Values | the garment_type vocabulary |
| Where | POST /v1/files (Upload) |
Output format
Each task delivers a fixed kind of file, stated in its
page's Specs, and every delivered file carries its media_type. A record's content is its data;
its url is a preview (Files and media).
Reproducibility
Each request starts a new job and can give a new result. To keep a result, keep its file.
Content filtering
A prompt or an image that is not accepted ends the request or the job with content_refused,
on every task (Task errors). Only delivered
outputs are charged (Pricing).
Value normalisation
Fields you do not send take the default in the task's schema; omitting an optional field and sending
null mean the same thing (Conventions).
A task takes exactly the fields in its schema: any other field is refused with
422 field_not_accepted, naming the field.