---
title: "Inserire un'immagine in un campo immagine"
description: "Inserire un'immagine stock, un risultato scelto o un file del sito in un campo immagine, includendo il testo alternativo, con una sola chiamata."
canonical: "https://atelier201.com/docs/it/api/media/place"
updated: "2026-11-06"
---

# Inserire un'immagine in un campo immagine

Richiede `sites:write`. Non costa crediti. Il percorso termina con `/images:place`. Modifica solo la bozza. I visitatori non vedranno nulla finché non [pubblichi](/docs/api/publishing/publish).

Una sola chiamata per «inserisci una foto qui». `target` è il campo immagine: `business:/hero/image` per l'immagine della home page oppure `<collection>/<slug>:/image` per una voce, ad esempio `services/sourdough:/image`. Il [modello dei contenuti](/docs/api/content/model) elenca i campi immagine.

Indica esattamente una sorgente:

- **`query`**: una descrizione in inglese, con parole concrete. Viene eseguita una ricerca nella libreria gratuita di immagini stock e il primo risultato viene importato con il relativo credito. `orientation` restringe i risultati in base al formato.
- **`stock_id`**: un risultato scelto con [Cercare immagini stock](/docs/api/media/stock-search).
- **`media_path`**: un file già presente nei file multimediali del sito, ad esempio una foto del proprietario.

Se i contenuti includono un campo alt (ad esempio `imageAlt`), il valore di `alt` viene salvato in quel campo accanto all'immagine e anche nel file multimediale. La modifica crea una sola voce nella cronologia e avvia la build: la risposta include `build`. Se la ricerca non trova nulla, viene restituito `404` e non viene scritto nulla.

```http
POST https://api.atelier201.com/v1/sites/{site_id}/images:place
```

## Authorizations

- `Authorization` (bearer, in header, required)

## Path parameters

- `site_id` (`string`, required): L'ID del sito o il suo slug (l'indirizzo prima di .atelier201.page).

## Body

`application/json`, required

- `target` (`string`, required, length: `3–200 chars`): Il campo immagine: business:/hero/image per i dettagli dell'attività oppure <collection>/<slug>:/image per una voce (services/sourdough:/image). get_content_model mostra i campi immagine.
- `alt` (`string`, required, length: `1–300 chars`): Descrizione di ciò che mostra l'immagine, per chi non può vederla, nella lingua del sito. Se presente, viene salvata nel campo alt accanto all'immagine.
- `query` (`string`, length: `≤ 100 chars`): Descrizione da cercare nella libreria di immagini stock gratuite, in inglese e con termini concreti ("minimalist concrete house at dusk"): viene importato il primo risultato.
- `stock_id` (`string`, length: `≤ 20 chars`): ID di un risultato di search_stock_media, se hai scelto personalmente l'immagine.
- `media_path` (`string`, length: `≤ 200 chars`): File già presente nei contenuti multimediali del sito (/media/storefront.jpg), ad esempio una foto del proprietario.
- `orientation` (`enum<string>`, one of: `landscape, portrait, square`): Con query: il formato da cercare. Per un hero è adatto Landscape.

## Response

**200**: Inserisci un'immagine in un campo immagine

- `data` (`Record<string, object>`, required)
- `data.target` (`string`, required)
- `data.image` (`string`, required): Il percorso /media attualmente presente nel campo.
- `data.alt` (`string`, required)
- `data.alt_field` (`string,null`, required): Dove è stato salvato il testo alternativo, oppure null se il contenuto non ha un campo per il testo alternativo.
- `data.credit` (`string,null`, required)
- `data.revision` (`string`, required, length: `40–40 chars`): ID di un commit Git (40 caratteri esadecimali) del repository del sito.
- `data.changed` (`boolean`, required)
- `data.build` (`object | null`, required): La build avviata (o a cui si è unita) questa modifica: l'anteprima la segue. Non serve chiamare build_site.
- `data.build.id` (`string`, required)
- `data.build.state` (`string`, required)
- `data.build.next_action` (`string`, required)
- `data.next_action` (`string`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "target": "<string>",
    "image": "<string>",
    "alt": "<string>",
    "alt_field": null,
    "credit": null,
    "revision": "<string>",
    "changed": true,
    "build": {
      "id": "<string>",
      "state": "<string>",
      "next_action": "<string>"
    },
    "next_action": "<string>"
  },
  "request_id": "<string>"
}
```

**400**: Codici possibili: invalid_request, unknown_field, invalid_parameter, invalid_cursor

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**401**: Codici possibili: authentication_required, invalid_api_key, api_key_expired, api_key_revoked

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**402**: Codici possibili: insufficient_credits

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**403**: Codici possibili: insufficient_scope, feature_not_available, admin_required

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**404**: Codici possibili: resource_not_found

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**409**: Codici possibili: conflict, result_not_ready, idempotency_key_reused

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**410**: Codici possibili: result_expired

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**413**: Codici possibili: request_too_large

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**422**: Codici possibili: request_too_large_for_plan

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**429**: Codici possibili: rate_limited

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**500**: Codici possibili: internal_error

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**503**: Codici possibili: service_unavailable

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `error.details` (`Record<string, object>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}
```

**Example request**

```bash
curl --request POST \
  --url 'https://api.atelier201.com/v1/sites/<site_id>/images:place' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "target": "<string>",
  "alt": "<string>"
}'
```