# 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](https://docs.refabric.com/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 |

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

:::note
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](https://docs.refabric.com/task-apis/pricing#what-sets-a-price)) |

```json
{ "image": "art:x1" }
{ "image": "https://example.com/look.jpg" }
```

:::tip
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](https://docs.refabric.com/task-apis/files-and-media#reuse-pass-a-file-back)).
:::

URLs are `https` only and must resolve to a public address. Pass a public `https` URL or an uploaded file
([Limits](https://docs.refabric.com/task-apis/limits#images-given-by-url)).

## 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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#use_case) vocabulary; `auto` picks the value for you |
| Cost effect | none |

```json
{ "prompt": "a jacket in this fabric",
  "references": [ { "image": "file:1234", "use_case": "fabric", "fidelity": 80 } ] }
```

:::note
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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#resolution) vocabulary, which also lists every task that takes it |
| Cost effect | `/estimate` prices your request |

```json
{ "resolution": "4K" }
```

## aspect_ratio

The shape of the result, as `width:height`.

| | |
|---|---|
| Type | `string` |
| Default | per task |
| Values | the [`aspect_ratio`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#aspect_ratio) vocabulary; each task lists the values it takes |
| Cost effect | none |

```json
{ "aspect_ratio": "3:4" }
```

:::note
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 |

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

```json
{ "models": ["model:4412", "model:5501"] }
```

:::note
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 |

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

```json
{ "background": { "type": "library", "background": "background:91aa" } }
```

:::note
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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#item_type) values a shoot can make (`ghost`, `flat`, `close_up`); `view`: the [`view_angle`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#view_angle) vocabulary |
| Cost effect | each made view is an image and a charge; a reused view is not charged again; see `/estimate` |

```json
{ "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`](https://docs.refabric.com/task-apis/vocabularies-and-concepts#garment_type) vocabulary |
| Where | `POST /v1/files` ([Upload](https://docs.refabric.com/task-apis/files-and-media#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](https://docs.refabric.com/task-apis/files-and-media#two-kinds)).

## 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](https://docs.refabric.com/task-apis/errors/task-errors#errors-inside-a-job)). Only delivered
outputs are charged ([Pricing](https://docs.refabric.com/task-apis/pricing#what-is-charged)).

## 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](https://docs.refabric.com/api-reference/platform/conventions#nulls-and-missing-fields)).
A task takes exactly the fields in its schema: any other field is refused with
`422 field_not_accepted`, naming the field.

## Related

::::cards
:::card{title="Vocabularies & concepts" href="/task-apis/vocabularies-and-concepts"}
Every value list, with what each value does and where it is used.
:::
:::card{title="Files and media" href="/task-apis/files-and-media"}
How files are uploaded, addressed and passed between tasks.
:::
:::card{title="Task API Reference" href="/task-api-reference"}
Each task's full input schema.
:::
::::