API di modifica Seedream 5.0: editing programmatico delle immagini

Le interfacce web sono ottime per modifiche occasionali. Le API sono il modo in cui si modificano 10.000 immagini in una notte. La Seedream 5.0 Edit API offre accesso programmatico allo stesso modello di editing in linguaggio naturale che alimenta la piattaforma Arteza, allo stesso prezzo di $0,10 per modifica. Questa guida illustra autenticazione, endpoint, esempi in Python e JavaScript, pattern per batch e best practice per la produzione.

In sintesi

• Accesso programmatico a Seedream 5.0 Edit a $0,10 per modifica (1 crediti)
• API REST con risposte JSON, generazione in 5-15 secondi
• Esempi in Python e JavaScript inclusi
• Progettata per flussi di lavoro batch: elabora migliaia di immagini per job
• 10 crediti gratuiti per i test su arteza.ai

Quando usare l'API e quando usare l'interfaccia web

Usa l'interfaccia web quando:

• Stai modificando 1-20 immagini manualmente
• Vuoi iterare visivamente
• Stai esplorando direzioni creative

Usa l'API quando:

• Stai modificando 50 o più immagini
• Stai costruendo un prodotto che modifica immagini
• Hai bisogno di prompt coerenti su un batch
• Vuoi integrare l'editing in una pipeline esistente (export da Lightroom, Shopify, CMS, ecc.)

Autenticazione

L'API utilizza l'autenticazione tramite bearer token. Ottieni la tua chiave API dalla Dashboard di Arteza dopo la registrazione.

# Salva la tua chiave come variabile d'ambiente
export SEEDANCE_API_KEY="your_api_key_here"

Non eseguire mai il commit delle chiavi API su git. Usa variabili d'ambiente, secret manager o file .env.

L'endpoint di modifica

Endpoint: POST https://api.arteza.ai/v1/edit

Parametri obbligatori:

Parametri facoltativi:

Ogni chiamata andata a buon fine scala 1 crediti.

Esempio in Python

import os
import requests

API_KEY = os.environ["SEEDANCE_API_KEY"]
API_URL = "https://api.arteza.ai/v1/edit"

def edit_image(image_path: str, prompt: str) -> bytes:
    with open(image_path, "rb") as f:
        files = {"image": f}
        data = {
            "prompt": prompt,
            "model": "seedream-5-lite-edit",
            "output_format": "png",
        }
        headers = {"Authorization": f"Bearer {API_KEY}"}
        response = requests.post(
            API_URL, files=files, data=data, headers=headers, timeout=60
        )
        response.raise_for_status()
        return response.content

# Utilizzo
edited = edit_image(
    "product.jpg",
    "Replace background with seamless white studio, add soft shadow"
)
with open("product_edited.png", "wb") as f:
    f.write(edited)

Esempio JavaScript / Node.js

import fs from "fs";
import FormData from "form-data";
import axios from "axios";

const API_KEY = process.env.SEEDANCE_API_KEY;
const API_URL = "https://api.arteza.ai/v1/edit";

async function editImage(imagePath, prompt) {
  const form = new FormData();
  form.append("image", fs.createReadStream(imagePath));
  form.append("prompt", prompt);
  form.append("model", "seedream-5-lite-edit");
  form.append("output_format", "png");

  const response = await axios.post(API_URL, form, {
    headers: {
      ...form.getHeaders(),
      Authorization: `Bearer ${API_KEY}`,
    },
    responseType: "arraybuffer",
    timeout: 60000,
  });

  return response.data;
}

// Utilizzo
const edited = await editImage(
  "product.jpg",
  "Apply warm golden-hour cinematic color grade"
);
fs.writeFileSync("product_edited.png", edited);

Esempio cURL

curl -X POST https://api.arteza.ai/v1/edit \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -F "[email protected]" \
  -F "prompt=Replace background with clean white studio" \
  -F "model=seedream-5-lite-edit" \
  -o product_edited.png

Vuoi risultati come questi? Prova Seedream 5.0 Edit gratis →

Pattern per l'elaborazione batch

Il caso d'uso più potente dell'API è il batch. Ecco un pattern Python pronto per la produzione:

import os
import concurrent.futures
from pathlib import Path

def process_batch(image_dir: str, prompt: str, output_dir: str, workers: int = 4):
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    images = list(Path(image_dir).glob("*.jpg"))

    def process_one(img_path: Path):
        try:
            result = edit_image(str(img_path), prompt)
            output_path = Path(output_dir) / f"{img_path.stem}_edited.png"
            with open(output_path, "wb") as f:
                f.write(result)
            return (img_path.name, "success")
        except Exception as e:
            return (img_path.name, f"error: {e}")

    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
        results = list(executor.map(process_one, images))

    for name, status in results:
        print(f"{name}: {status}")

# Modifica 100 foto di prodotto con lo stesso prompt
process_batch(
    image_dir="./raw_products",
    prompt="Replace background with pure white studio, soft shadow beneath",
    output_dir="./edited_products",
    workers=4,
)

Prestazioni: con 4 worker, 100 immagini richiedono circa 3-5 minuti in totale. Costo: 100 x 1 credito = 100 crediti = $10 in totale.

Gestione degli errori

L'API restituisce codici di stato HTTP standard:

Pattern di retry

import time
import requests

def edit_with_retry(image_path: str, prompt: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            return edit_image(image_path, prompt)
        except requests.HTTPError as e:
            if e.response.status_code in (429, 500, 502, 503, 504):
                wait = 2 ** attempt  # exponential backoff: 1s, 2s, 4s
                time.sleep(wait)
                continue
            raise
    raise Exception("Max retries exceeded")

Flusso di lavoro con webhook per batch di grandi dimensioni

Per job con migliaia di immagini, usa i webhook per evitare il polling continuo:

# Invia un job con un URL webhook
response = requests.post(
    f"{API_URL}/batch",
    json={
        "model": "seedream-5-lite-edit",
        "images": ["s3://bucket/img1.jpg", "s3://bucket/img2.jpg", ...],
        "prompt": "Replace background with white studio",
        "webhook": "https://yourapp.com/webhook/seedance",
    },
    headers={"Authorization": f"Bearer {API_KEY}"},
)
job_id = response.json()["job_id"]

# Arteza invierà i risultati al tuo webhook al termine del job

Limiti di frequenza

Se hai bisogno di limiti più elevati, contatta il supporto dalla tua dashboard.

Pattern comuni per la produzione

1. Pipeline prodotti Shopify

# Preleva nuovi prodotti da Shopify → modifica → carica di nuovo
for product in new_products:
    for image_url in product.images:
        edited = edit_image_url(image_url, BRAND_PROMPT)
        upload_to_shopify(product.id, edited)

Consulta guida alle foto di prodotto per idee sui prompt.

2. Automazione degli annunci immobiliari

# Migliora automaticamente le foto dei nuovi annunci
for photo in listing.photos:
    if photo.type == "exterior":
        edited = edit_image(photo.path, "Replace sky with blue clear sky, brighten")
    elif photo.type == "interior_empty":
        edited = edit_image(photo.path, "Stage in modern Scandinavian style")
    save_to_mls(edited)

Consulta guida all'home staging virtuale per i modelli di prompt.

3. Pipeline di contenuti per i social media

# Genera varianti multi-piattaforma per ogni post
for source_image in incoming_posts:
    instagram = edit_image(source_image, "Bright airy Instagram aesthetic")
    tiktok = edit_image(source_image, "High-energy saturated TikTok look")
    linkedin = edit_image(source_image, "Clean corporate LinkedIn tones")
    publish_to_platforms(instagram, tiktok, linkedin)

Consulta guida ai social media.

Monitoraggio dei costi

Ogni chiamata API scala 1 crediti. Monitora le tue spese in modo programmatico:

def get_credit_balance():
    response = requests.get(
        "https://api.arteza.ai/v1/account/credits",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    return response.json()["balance"]

print(f"Crediti rimanenti: {get_credit_balance()}")

Prezzi

I crediti mensili si rinnovano a ogni ciclo di fatturazione. I crediti acquistati non scadono mai. Prezzi completi.

Checklist per la produzione

• Chiave API conservata in modo sicuro (variabile d'ambiente o secret manager)
• Logica di retry con exponential backoff
• Logging degli errori e sistema di avvisi
• Monitoraggio del saldo crediti
• Concorrenza consapevole dei limiti di frequenza
• Validazione delle dimensioni delle immagini in input (<2048px)
• Storage dell'output (CDN, S3, ecc.)
• Template di prompt versionati su git

Prossimi passi

• Guida completa a Seedream 5.0 Edit
• Flussi di lavoro per la fotografia di prodotto
• Automazione per il settore immobiliare
• Creare varianti su larga scala

Ottieni la tua chiave API gratis → - crediti gratuiti alla registrazione, nessuna carta richiesta.