---
title: "Bild in ein Bildfeld einfügen"
description: "Mit einem einzigen Aufruf ein Stockfoto, ein ausgewähltes Suchergebnis oder eine Datei der Website samt Alternativtext in ein Bildfeld einfügen."
canonical: "https://atelier201.com/docs/de/api/media/place"
updated: "2026-11-06"
---

# Bild in ein Bildfeld einfügen

Erfordert `sites:write`. Kostet keine Credits. Der Pfad endet mit `/images:place`. Es wird nur der Entwurf geändert. Besucher sehen die Änderung erst, wenn Sie [veröffentlichen](/docs/api/publishing/publish).

Ein Aufruf für „Hier ein Foto einfügen“. `target` bezeichnet das Bildfeld: `business:/hero/image` für das Bild auf der Startseite oder `<collection>/<slug>:/image` für einen Eintrag, zum Beispiel `services/sourdough:/image`. Die [Inhaltsstruktur](/docs/api/content/model) führt die Bildfelder auf.

Geben Sie genau eine Quelle an:

- **`query`**: eine Beschreibung auf Englisch mit konkreten Begriffen. Die kostenlose Stock-Bildbibliothek wird durchsucht und das erste Ergebnis samt Quellenangabe importiert. Mit `orientation` lässt sich das Bildformat eingrenzen.
- **`stock_id`**: ein Suchergebnis, das Sie über [Stock-Medien durchsuchen](/docs/api/media/stock-search) ausgewählt haben.
- **`media_path`**: eine Datei, die sich bereits in den Medien der Website befindet, zum Beispiel ein eigenes Foto des Inhabers.

`alt` wird im Alt-Feld neben dem Bild gespeichert, sofern der Inhalt eines hat (zum Beispiel `imageAlt`), und auch bei der Mediendatei. Die Änderung bildet einen Verlaufseintrag und der Build startet: Die Antwort enthält `build`. Ergibt die Suche keinen Treffer, wird `404` zurückgegeben und es werden keine Änderungen vorgenommen.

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

## Authorizations

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

## Path parameters

- `site_id` (`string`, required): ID der Website oder ihr Slug (die Adresse vor .atelier201.page).

## Body

`application/json`, required

- `target` (`string`, required, length: `3–200 chars`): Das Bildfeld: business:/hero/image für Unternehmensdetails oder <collection>/<slug>:/image für einen Eintrag (services/sourdough:/image). get_content_model zeigt die Bildfelder an.
- `alt` (`string`, required, length: `1–300 chars`): Beschreibt in der Sprache der Website, was auf dem Bild zu sehen ist, für Menschen, die es nicht sehen können. Wird neben dem Bild im Feld alt gespeichert, sofern dieses vorhanden ist.
- `query` (`string`, length: `≤ 100 chars`): Eine Suchbeschreibung für die kostenlose Stock-Bibliothek. Auf Englisch und mit konkreten Begriffen, etwa „minimalist concrete house at dusk“: Das erste Ergebnis wird importiert.
- `stock_id` (`string`, length: `≤ 20 chars`): Eine Ergebnis-ID von search_stock_media, wenn du das Bild selbst ausgewählt hast.
- `media_path` (`string`, length: `≤ 200 chars`): Eine Datei, die sich bereits in den Medien der Website befindet (/media/storefront.jpg), zum Beispiel ein eigenes Foto des Inhabers.
- `orientation` (`enum<string>`, one of: `landscape, portrait, square`): Mit query: das gesuchte Format. Landscape eignet sich für ein Hero-Bild.

## Response

**200**: Bild in ein Bildfeld einfügen

- `data` (`Record<string, object>`, required)
- `data.target` (`string`, required)
- `data.image` (`string`, required): Der /media-Pfad, der derzeit im Feld steht.
- `data.alt` (`string`, required)
- `data.alt_field` (`string,null`, required): Gibt an, wo der Alternativtext gespeichert wurde, oder null, wenn der Inhalt kein Alternativtextfeld hat.
- `data.credit` (`string,null`, required)
- `data.revision` (`string`, required, length: `40–40 chars`): Eine Git-Commit-ID (40 hexadezimale Zeichen) des Repositorys der Website.
- `data.changed` (`boolean`, required)
- `data.build` (`object | null`, required): Der Build, den diese Änderung gestartet oder übernommen hat: Die Vorschau folgt diesem Build. Kein Aufruf von build_site erforderlich.
- `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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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**: Mögliche Codes: 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>"
}'
```