media

Creare un'immagine o un video con l'AI

Il costo viene scalato dai crediti del workspace, a prezzo fisso per modello. Effettua prima una chiamata con estimate_only: true (gratuita) per conoscere il prezzo esatto, poi ripeti la chiamata impostando max_credits su quell’importo. In genere un’immagine è pronta entro wait_seconds; un video richiede da uno a cinque minuti: recupera la generazione con GET usando il suo id. Se la generazione non riesce, i crediti vengono restituiti.

POST/v1/sites/{site_id}/media/generations

Request

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>"
}'

import json
import requests

url = "https://api.atelier201.com/v1/sites/<site_id>/media/generations"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"model\":\"gpt-image\",\"prompt\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.atelier201.com/v1/sites/<site_id>/media/generations", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "gpt-image",
    "prompt": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.atelier201.com/v1/sites/<site_id>/media/generations");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"model\":\"gpt-image\",\"prompt\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.atelier201.com/v1/sites/<site_id>/media/generations", bytes.NewBuffer([]byte("{\"model\":\"gpt-image\",\"prompt\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.atelier201.com/v1/sites/<site_id>/media/generations"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"model\":\"gpt-image\",\"prompt\":\"<string>\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.atelier201.com/v1/sites/<site_id>/media/generations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"model\":\"gpt-image\",\"prompt\":\"<string>\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/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>"
}

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

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

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

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

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

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

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

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

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

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

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

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

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.

Effettua la chiamata con estimate_only: true. Non costa nulla e restituisce estimated_credits (il prezzo esatto) e balance.
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 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.

Autorizzazioni

Authorizationbearerin headerrequired

Parametri di percorso

site_idstringrequired

L'ID del sito o il suo slug (l'indirizzo prima di .atelier201.page).

Corpo

application/jsonrequired

modelenum<string>requiredone 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.

promptstringrequiredlength: 1–4000 chars

Cosa mostrare: soggetto, ambientazione, luce, inquadratura, stile.

aspect_ratioenum<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).

qualityenum<string>one of: draft, standard, high

Immagini: draft, standard (predefinito) o high.

durationintegerrange: 1–10

Video: durata in secondi.

resolutionenum<string>one of: 480p, 720p, 768p, 1080p, 2k

Video: per impostazione predefinita, la risoluzione del modello (720p, oppure 768p per minimax e p-video).

audioboolean

Video: con audio (solo seedance).

filenamestringlength: 1–100 chars

Un nome senza estensione.

altstringlength: ≤ 300 chars

estimate_onlyboolean

true: prezzo esatto in crediti e saldo. Gratuito, non viene avviata alcuna operazione.

max_creditsintegerrange: ≤ 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_secondsintegerrange: 0–55

Per quanto tempo attendere il risultato. Valore predefinito: 50 per un’immagine, 0 per un video.

Risposta

application/json

Crea un’immagine o un video con l’AI

dataRecord<string, object>required

Show child attributes

data.idstring

L’id della generazione: esegui GET finché lo status non è succeeded o failed.

data.statusenum<string>one of: running, succeeded, failed

data.mediaobject | null

Show child attributes

data.media.pathstringrequired

data.media.url_pathstringrequired

data.media.mimestringrequired

data.media.sizeintegerrequiredrange: -9007199254740991–9007199254740991

data.media.altstringnullrequired

data.media.creditstringnullrequired

Autore, se richiesto dalla licenza: "Photo by Jane Doe on Pixabay", "Generated with Seedream 5 Lite (ByteDance)". Null per un caricamento.

data.media.keep_originalbooleanrequired

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.errorstringnull

data.creditsinteger | null

Il costo effettivo.

data.credits_refundedinteger | null

Restituiti in caso di errore.

data.estimated_creditsintegerrange: -9007199254740991–9007199254740991

estimate_only: il prezzo esatto che verrebbe applicato.

data.balancenumber

estimate_only: il saldo attuale di crediti del workspace.

data.next_actionstringnullrequired

request_idstringrequired

Creare un'immagine o un video con l'AI

Autorizzazioni

Parametri di percorso

Corpo

Risposta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown

Cookie