---
title: "Creare un'immagine o un video con l'AI"
description: "Generare un'immagine o un breve video nei file multimediali del sito, pagando in crediti a prezzo fisso."
canonical: "https://atelier201.com/docs/it/api/media/generate"
updated: "2026-11-06"
---

# Creare un'immagine o un video con l'AI

Richiede `media:generate`, un'autorizzazione specifica: una credenziale che può modificare i siti non può spendere crediti, a meno che non abbia ricevuto anche questa autorizzazione. Consuma i crediti dell'area di lavoro.

1. Effettua la chiamata con `estimate_only: true`. Non costa nulla e restituisce `estimated_credits` (il prezzo esatto) e `balance`.
2. Ripeti la chiamata impostando `max_credits` su quel prezzo. Senza `max_credits`, la chiamata viene rifiutata. Se il prezzo lo supera, la chiamata viene rifiutata senza addebiti: `invalid_parameter` su `max_credits`, con `details.reason` `price_above_max_credits`, `details.estimated_credits` e `details.max_credits`.

I crediti vengono addebitati all'avvio della generazione. Se non va a buon fine, vengono restituiti. Di solito un'immagine è pronta entro `wait_seconds` (50 per impostazione predefinita) e la risposta include `status: succeeded` e il relativo `media`. Un video richiede da uno a cinque minuti: la risposta è `status: running` con un `id`; [recupera la generazione](/docs/api/media/generation) finché non è terminata.

Il file viene salvato nei file multimediali del sito come un file caricato, con `credit` impostato sul modello che lo ha creato. Non presentare mai un'immagine generata come una fotografia dell'attività, dei suoi prodotti, delle persone che vi lavorano o dei suoi locali.

Al massimo 10 generazioni al minuto per area di lavoro (`429 rate_limited` oltre tale limite, con `details.retry_after_seconds`). Crediti insufficienti: `402 insufficient_credits` con `details.needed` e `details.balance`. Se un modello è occupato, la generazione non va a buon fine e i crediti vengono restituiti: riprova tra un minuto.

```http
POST https://api.atelier201.com/v1/sites/{site_id}/media/generations
```

## 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

- `model` (`enum<string>`, required, one of: `gpt-image, nano-banana, flux, p-image, wan, minimax, seedance, p-video`): GET /v1/media/models elenca tutti i modelli, indica a cosa sono più adatti e i relativi prezzi in crediti.
- `prompt` (`string`, required, length: `1–4000 chars`): Cosa mostrare: soggetto, ambientazione, luce, inquadratura, stile.
- `aspect_ratio` (`enum<string>`, one of: `16:9, 1:1, 9:16, 4:3, 3:4, 3:2, 2:3`): Rapporto tra larghezza e altezza. Ogni modello accetta i rapporti indicati da list_media_models; per impostazione predefinita usa il primo (16:9 per la maggior parte dei modelli).
- `quality` (`enum<string>`, one of: `draft, standard, high`): Immagini: draft, standard (predefinito) o high.
- `duration` (`integer`, range: `1–10`): Video: durata in secondi.
- `resolution` (`enum<string>`, one of: `480p, 720p, 768p, 1080p, 2k`): Video: per impostazione predefinita, la risoluzione del modello (720p, oppure 768p per minimax e p-video).
- `audio` (`boolean`): Video: con audio (solo seedance).
- `filename` (`string`, length: `1–100 chars`): Un nome senza estensione.
- `alt` (`string`, length: `≤ 300 chars`)
- `estimate_only` (`boolean`): true: prezzo esatto in crediti e saldo. Gratuito, non viene avviata alcuna operazione.
- `max_credits` (`integer`, range: `≤ 9007199254740991`): Obbligatorio per avviare l’operazione: l’importo massimo che accetti di spendere. Se il prezzo è superiore, la richiesta viene rifiutata e non viene addebitato nulla. Usa il valore ottenuto con una chiamata estimate_only.
- `wait_seconds` (`integer`, range: `0–55`): Per quanto tempo attendere il risultato. Valore predefinito: 50 per un’immagine, 0 per un video.

## Response

**202**: Crea un’immagine o un video con l’AI

- `data` (`Record<string, object>`, required)
- `data.id` (`string`): L’id della generazione: esegui GET finché lo status non è succeeded o failed.
- `data.status` (`enum<string>`, one of: `running, succeeded, failed`)
- `data.media` (`object | null`)
- `data.media.path` (`string`, required)
- `data.media.url_path` (`string`, required)
- `data.media.mime` (`string`, required)
- `data.media.size` (`integer`, required, range: `-9007199254740991–9007199254740991`)
- `data.media.alt` (`string,null`, required)
- `data.media.credit` (`string,null`, required): Autore, se richiesto dalla licenza: "Photo by Jane Doe on Pixabay", "Generated with Seedream 5 Lite (ByteDance)". Null per un caricamento.
- `data.media.keep_original` (`boolean`, required): Memorizzato esattamente come caricato e mai ricodificato durante una build. Altrimenti, un'immagine di oltre 200 KB viene compressa al caricamento (massimo 2000 px, fino a circa 150 KB, qualità pari o superiore a 75, metadati rimossi).
- `data.error` (`string,null`)
- `data.credits` (`integer | null`): Il costo effettivo.
- `data.credits_refunded` (`integer | null`): Restituiti in caso di errore.
- `data.estimated_credits` (`integer`, range: `-9007199254740991–9007199254740991`): estimate_only: il prezzo esatto che verrebbe applicato.
- `data.balance` (`number`): estimate_only: il saldo attuale di crediti del workspace.
- `data.next_action` (`string,null`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "id": "<string>",
    "status": "running",
    "media": {
      "path": "<string>",
      "url_path": "<string>",
      "mime": "<string>",
      "size": 123,
      "alt": null,
      "credit": null,
      "keep_original": true
    },
    "error": null,
    "credits": 123,
    "credits_refunded": 123,
    "estimated_credits": 123,
    "balance": 123.45,
    "next_action": null
  },
  "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>/media/generations' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image",
  "prompt": "<string>"
}'
```