Seedream v4.5 Edit API: programmatische beeldbewerking

Seedream v4.5 Edit uitvoeren via de Arteza-interface werkt prima voor losse bewerkingen en kleine batches. Voor workflows met een hoog volume, zoals catalogi met duizenden SKU's, dynamische beeldgeneratie per gebruiker en door een CMS aangestuurde asset-pipelines, wil je API-toegang. Deze gids behandelt de endpointstructuur, requestparameters, responsverwerking en productiepatronen voor het bouwen van geautomatiseerde beeldbewerkingssystemen op Seedream v4.5.

Samenvatting

• Seedream v4.5 Edit is beschikbaar via het fal-ai/bytedance/seedream/v4.5/edit-endpoint
• Dezelfde prijzen per afbeelding als in de UI: 1 credits ($0,10)
• Accepteert maximaal 10 invoer-URL's voor afbeeldingen plus een tekstprompt
• 4MP (2048×2048) uitvoer, geretourneerd als afbeeldings-URL
• Typische generatietijd van 30-60 seconden: gebruik asynchrone patronen voor productie

Waarom de API gebruiken

De API maakt automatiseringspatronen mogelijk die de UI niet kan evenaren:

• Batches met hoog volume. Verwerk 1.000+ bewerkingen in één pipeline-run.
• Dynamische generatie. Bouw afbeeldingen op aanvraag op basis van gebruikersdata of databaserecords.
• Geplande workflows. Nachtelijke catalogusupdates, door gebeurtenissen getriggerde regeneratie.
• Integratie met bestaande stacks. Node.js, Python, Go, Ruby: elke HTTP-client werkt.
• Reproduceerbare productie. Versiebeheerde scripts in plaats van handmatige klikken.

Als jouw gebruik meer dan 20-50 vergelijkbare bewerkingen omvat, is de API de instelling waard.

Endpointstructuur

Het Seedream v4.5 Edit-model is beschikbaar op:

fal-ai/bytedance/seedream/v4.5/edit

Dit is een standaard fal.ai-modelendpoint dat direct of via het Arteza-creditsysteem kan worden aangeroepen.

Authenticatie

Arteza API-verzoeken worden geverifieerd via een API-sleutel die als Bearer-token wordt meegegeven in de Authorization-header.

Je API-sleutel ophalen

1. Log in via arteza.ai
2. Ga naar je accountinstellingen
3. Zoek de API-sectie
4. Genereer een nieuwe API-sleutel
5. Bewaar hem veilig: behandel hem als een wachtwoord

Leg je API-sleutel nooit vast in versiebeheer. Gebruik omgevingsvariabelen:

export SEEDANCE_API_KEY="your_api_key_here"

Authenticatieheader

Authorization: Bearer your_api_key_here

Requeststructuur

Een eenvoudig Seedream v4.5 Edit-verzoek ziet er zo uit:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Parameterreferentie

Er kunnen maximaal 10 afbeeldings-URL's worden meegegeven. Het model behandelt de eerste afbeelding als primair en de volgende afbeeldingen als referenties.

Voorbeeldverzoek: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Voorbeeldverzoek: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Responsstructuur

Een succesvolle respons bevat de gegenereerde afbeeldings-URL's:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Download de afbeelding via de geretourneerde URL: uitvoer-URL's zijn 24 uur geldig.

Asynchroon generatiepatroon

Seedream v4.5 Edit vergt 30-60 seconden per verzoek. Voor productie wil je waarschijnlijk asynchrone generatie met webhooks of polling in plaats van blokkerende verzoeken.

Asynchroon met webhooks

Geef een webhook_url mee in je verzoek en Arteza stuurt het resultaat via POST wanneer de generatie is voltooid:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Je webhookhandler ontvangt:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

Webhookverwerking is het aanbevolen productiepatroon.

Begin nu met bouwen. Probeer de tool eerst.

Asynchroon met polling

Als je infrastructuur geen webhooks kan ontvangen, poll je voor de status:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Poll op voltooiing
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Poll elke 5-10 seconden. De totale wachttijd bedraagt doorgaans 30-60 seconden.

Productiepatronen

Patroon 1: Batchgeneratie voor catalogi

Voer de API uit over je productcatalogus om consistente achtergrondwisselingen te genereren voor elke SKU:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Combineer dit met een webhookhandler die uitvoer opslaat op je CDN en het productrecord bijwerkt.

Patroon 2: Bewerkingen op aanvraag door gebruikers

Laat gebruikers afbeeldingen uploaden en AI-bewerkte resultaten op aanvraag ontvangen:

1. Gebruiker uploadt afbeelding naar je bucket
2. Je backend roept Seedream v4.5 Edit aan met een door de gebruiker gekozen prompt
3. Poll of wacht op webhook
4. Stuur de resultaat-URL terug naar de client van de gebruiker

Reken in je UX op ongeveer 60 seconden wachttijd per bewerking.

Patroon 3: Door CMS aangestuurde asset-pipeline

Wanneer content wordt gepubliceerd in je CMS, worden bijbehorende afbeeldingen automatisch gegenereerd:

1. CMS stuurt een publicatie-event
2. Serverloze functie wordt getriggerd
3. Roept Seedream v4.5 Edit aan met een sjabloonprompt
4. Slaat het resultaat op op CDN
5. Werkt het CMS-record bij met de afbeeldings-URL

Dit patroon elimineert handmatig afbeeldingen aanmaken bij publicaties met hoog volume.

Foutafhandeling

Veelvoorkomende foutresponsen:

Omsluit API-aanroepen altijd in try/except met herhaalpogingen voor 429- en 500-responsen.

Snelheidslimieten

Arteza hanteert redelijke snelheidslimieten op de API. Voor de meeste productieworkflows kom je er niet aan, maar voor bulkbatches van 1.000+ verzoeken implementeer je het volgende:

• Exponentiële terugval bij 429-responsen
• Limieten voor gelijktijdige verzoeken (begin met 5 parallel, schakel omhoog)
• Verzoekwachtrijen voor voorspelbare doorvoer

Neem contact op met de support voor hogere snelheidslimieten bij zware productiebelasting.

Kosten bij API-volume

API-aanroepen kosten hetzelfde als UI-aanroepen: 1 credits ($0,10) per afbeelding. Voor planningsdoeleinden:

• 100 API-aanroepen = 100 credits (ruim binnen het Starter-abonnement van $5)
• 1.000 API-aanroepen = 1.000 credits (het Studio-abonnement van $120, 1.800 per maand)
• 10.000 API-aanroepen = 10.000 credits (het Studio-abonnement van $120 plus ongeveer 8.200 credits aan bijvullingen)

Voor volumes boven 10.000 per maand kun je contact opnemen met het team voor aangepaste prijzen.

Aanbevolen werkwijzen

1. Gebruik webhooks in productie. Polling werkt, maar verspilt resources.
2. Bewaar prompts in versiebeheer. Behandel prompts als code.
3. Log alles. Verzoek-ID's, prompts, uitvoer, fouten.
4. Valideer invoer voordat je aanroept. Slechte afbeeldings-URL's verspillen credits.
5. Houd je creditbalans in de gaten. Stuur een waarschuwing wanneer je onder een drempel komt.
6. Test promptwijzigingen in staging. Valideer op 3-5 afbeeldingen voordat je een volledige batch uitvoert.
7. Cache resultaten. Als de invoer identiek is, hergebruik dan eerdere uitvoer.

Verder lezen

• Volledige Seedream v4.5 bewerkingsgids
• Tutorial voor batchbewerking
• Prijsoverzicht

Aan de slag

Genereer je API-sleutel in het Arteza-dashboard, claim 10 gratis credits en voer het bovenstaande Node.js-voorbeeld uit met een productfoto. De API ontgrendelt het volledige productiepotentieel van Seedream v4.5 Edit: zodra alles is ingesteld, draait het om promptengineering. Wil je eerst hands-on testen, open de webtool en valideer je prompts voordat je automatiseert.