media

Crear una imagen o un vídeo con IA

Se paga con los créditos del espacio de trabajo, a un precio fijo por modelo. Haz primero una llamada con estimate_only: true (gratis) para conocer el precio exacto y, después, otra con max_credits establecido en ese importe. Las imágenes suelen estar listas dentro del plazo de wait_seconds; los vídeos tardan entre uno y cinco minutos. Consulta la generación con GET usando su id. Si una generación falla, se devuelven los créditos.

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

Requiere media:generate, un permiso independiente. Una credencial que permita editar sitios no puede gastar créditos salvo que también tenga este permiso. Se descuentan créditos del espacio de trabajo.

Haz la llamada con estimate_only: true. No cuesta nada y devuelve estimated_credits (el precio exacto) y balance.
Vuelve a hacer la llamada con max_credits establecido en ese precio. Sin max_credits, se rechaza la llamada. Si el precio supera ese límite, la llamada se rechaza sin cobrar nada: invalid_parameter en max_credits, con details.reason price_above_max_credits, details.estimated_credits y details.max_credits.

Los créditos se cobran cuando empieza la generación. Si falla, se devuelven. Normalmente, una imagen está lista en wait_seconds (50 de forma predeterminada) y la respuesta incluye status: succeeded y su media. Un vídeo tarda entre uno y cinco minutos: la respuesta es status: running con un id. Consulta la generación hasta que termine.

El archivo se añade a los archivos multimedia del sitio como si se hubiera subido, con credit establecido en el modelo que lo ha creado. No presentes nunca una imagen generada como si fuera una fotografía del negocio, sus productos, su personal o sus instalaciones.

Se permiten como máximo 10 generaciones por minuto y espacio de trabajo. Si se supera el límite, se devuelve 429 rate_limited con details.retry_after_seconds. Si no hay créditos suficientes, se devuelve 402 insufficient_credits con details.needed y details.balance. Si el modelo está ocupado, la generación falla y se devuelven los créditos. Vuelve a intentarlo dentro de un minuto.

Autorizaciones

Authorizationbearerin headerrequired

Parámetros de ruta

site_idstringrequired

El ID del sitio o su slug (la dirección antes de .atelier201.page).

Cuerpo

application/jsonrequired

modelenum<string>requiredone of: gpt-image, nano-banana, flux, p-image, wan, minimax, seedance, p-video

GET /v1/media/models muestra cada modelo, para qué es más adecuado y sus precios en créditos.

promptstringrequiredlength: 1–4000 chars

Qué mostrar: tema, entorno, iluminación, encuadre y estilo.

aspect_ratioenum<string>one of: 16:9, 1:1, 9:16, 4:3, 3:4, 3:2, 2:3

Relación entre anchura y altura. Cada modelo admite las proporciones que devuelve list_media_models. Si no se indica ninguna, se usa la primera (16:9 en la mayoría de los casos).

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

Imágenes: borrador, estándar (predeterminado) o alta.

durationintegerrange: 1–10

Vídeos: duración en segundos.

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

Vídeos: por defecto, la resolución del modelo (720p o 768p para minimax y p-video).

audioboolean

Vídeos: con sonido (solo seedance).

filenamestringlength: 1–100 chars

Un nombre sin extensión.

altstringlength: ≤ 300 chars

estimate_onlyboolean

true: el precio exacto en créditos y el saldo. Es gratis y no se ejecuta nada.

max_creditsintegerrange: ≤ 9007199254740991

Obligatorio para ejecutar: el máximo que aceptas gastar. Se rechaza la solicitud y no se cobra nada si el precio es superior. Obtén este valor con una llamada estimate_only.

wait_secondsintegerrange: 0–55

Cuánto tiempo esperar el resultado. El valor predeterminado es 50 para una imagen y 0 para un vídeo.

Respuesta

application/json

Crea una imagen o un vídeo con IA

dataRecord<string, object>required

Show child attributes

data.idstring

El id de la generación. Haz GET hasta que el estado sea 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

Quién lo creó, cuando la licencia lo requiere: "Photo by Jane Doe on Pixabay", "Generated with Seedream 5 Lite (ByteDance)". Null si se ha subido el archivo.

data.media.keep_originalbooleanrequired

Se almacena exactamente como se ha subido y nunca se vuelve a codificar durante una compilación. De lo contrario, las imágenes de más de 200 KB se comprimen al subirlas (máximo 2000 px, objetivo de 150 KB, calidad de 75 o superior y metadatos eliminados).

data.errorstringnull

data.creditsinteger | null

Lo que ha costado.

data.credits_refundedinteger | null

Se devuelve si se produce un error.

data.estimated_creditsintegerrange: -9007199254740991–9007199254740991

estimate_only: el precio exacto que tendría.

data.balancenumber

estimate_only: los créditos disponibles ahora en el espacio de trabajo.

data.next_actionstringnullrequired

request_idstringrequired

Crear una imagen o un vídeo con IA

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown

Cookies