Seedream v4.5 API: integracja obrazów AI z Twoją aplikacją

Integracja generowania obrazów AI z aplikacją oznaczała dotychczas wybór spośród trzech złych opcji: uruchomienie Stable Diffusion samodzielnie (kosztowna infrastruktura), płacenie według stawek OpenAI za token (nieprzewidywalne koszty) lub zobowiązanie się do subskrypcji API (marnowanie przepustowości). API Seedream v4.5 działa inaczej: płacisz za obraz po $0.10, standardowe REST i czas odpowiedzi mierzony w sekundach. Ten przewodnik przeprowadzi cię od zera do pierwszego wygenerowanego obrazu w mniej niż 10 minut.

W skrócie

• API Seedream v4.5 kosztuje 1 kredytów ($0,10) za obraz
• Standardowe REST API z żądaniami i odpowiedziami w formacie JSON
• Parametry: prompt, rozdzielczość, proporcje obrazu, num_images (1-6), skala prowadzenia
• Typowy czas odpowiedzi: 5-15 sekund na generowanie
• Plany od $5 miesięcznie - kredyty są pobierane tylko podczas generowania

Do czego nadaje się API

API Seedream v4.5 sprawdza się w aplikacjach, które potrzebują generowania obrazów AI na żądanie przy przewidywalnych kosztach za obraz. Typowe zastosowania:

Produkty SaaS, które pozwalają użytkownikom generować obrazy w ramach ich przepływu pracy, takie jak narzędzia projektowe, platformy marketingowe czy aplikacje do tworzenia treści.

Platformy e-commerce programowo generujące zdjęcia lifestyle'owe produktów lub nagłówki kategorii.

Narzędzia do automatyzacji marketingu produkujące wizualizacje kampanii na podstawie ustrukturyzowanych danych wejściowych.

Systemy zarządzania treścią oferujące generowanie obrazów AI jako natywną funkcję.

Projekty deweloperskie i skrypty automatyzacji dla każdego przepływu pracy wymagającego generowania obrazów na dużą skalę.

Aplikacje mobilne wywołujące API z usługi backendowej, aby przenieść generowanie obrazów poza urządzenie.

Jeśli twoje zastosowanie pasuje do któregoś z tych przypadków, ten przewodnik pozwoli ci szybko przeprowadzić integrację.

Uwierzytelnianie i pierwsze kroki

Krok 1: Uzyskaj klucz API

Zarejestruj się konto w Arteza, jeśli jeszcze go nie masz. Przejdź do ustawień konta i wygeneruj klucz API. Traktuj ten klucz jak hasło - nie umieszczaj go w publicznych repozytoriach.

Krok 2: Doładuj konto kredytami

Użycie API pobiera środki z tego samego salda kredytowego co korzystanie z wersji webowej. Twoje 10 darmowe kredyty za rejestrację działają przy wywołaniach API. Do użytku produkcyjnego wykup subskrypcję w strona z cenami już od $5.

Krok 3: Wyślij pierwsze żądanie

Endpoint API dla Seedream v4.5 to:

POST https://api.arteza.ai/v1/images/generate

Minimalna treść żądania:

{
  "model": "seedream-v4-5",
  "prompt": "A cozy bookstore at dusk, warm window light",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

Umieść klucz API w nagłówku Authorization:

Authorization: Bearer YOUR_API_KEY

Pełna dokumentacja parametrów

Obsługiwane rozdzielczości

Seedream v4.5 obsługuje wiele opcji rozdzielczości do 4 megapikseli:

Przykłady kodu

Node.js (Fetch)

const generateImage = async (prompt) => {
  const response = await fetch(
    'https://api.arteza.ai/v1/images/generate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SEEDANCE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'seedream-v4-5',
        prompt: prompt,
        width: 2048,
        height: 2048,
        num_images: 1,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`Błąd API: ${response.status}`);
  }

  const data = await response.json();
  return data.images[0].url;
};

// Użycie
const imageUrl = await generateImage(
  'A cozy bookstore at dusk, warm window light, editorial photography'
);
console.log(imageUrl);

Python (Requests)

import os
import requests

def generate_image(prompt, width=2048, height=2048, num_images=1):
    response = requests.post(
        'https://api.arteza.ai/v1/images/generate',
        headers={
            'Authorization': f'Bearer {os.environ["SEEDANCE_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'seedream-v4-5',
            'prompt': prompt,
            'width': width,
            'height': height,
            'num_images': num_images,
        },
    )
    response.raise_for_status()
    data = response.json()
    return [img['url'] for img in data['images']]

# Użycie
urls = generate_image(
    'An editorial product photograph of a ceramic coffee mug, '
    'warm morning light, minimalist composition'
)
print(urls)

cURL

curl -X POST https://api.arteza.ai/v1/images/generate \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-5",
    "prompt": "A futuristic city skyline at sunset, cinematic photography",
    "width": 2048,
    "height": 1152,
    "num_images": 1
  }'

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type GenerateRequest struct {
    Model     string `json:"model"`
    Prompt    string `json:"prompt"`
    Width     int    `json:"width"`
    Height    int    `json:"height"`
    NumImages int    `json:"num_images"`
}

func generateImage(prompt string) (string, error) {
    reqBody := GenerateRequest{
        Model:     "seedream-v4-5",
        Prompt:    prompt,
        Width:     2048,
        Height:    2048,
        NumImages: 1,
    }

    jsonData, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest(
        "POST",
        "https://api.arteza.ai/v1/images/generate",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SEEDANCE_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    images := result["images"].([]interface{})
    firstImage := images[0].(map[string]interface{})
    return firstImage["url"].(string), nil
}

Format odpowiedzi

Poprawne odpowiedzi zwracają JSON o następującej strukturze:

{
  "id": "gen_abc123xyz",
  "model": "seedream-v4-5",
  "created": 1712764800,
  "images": [
    {
      "url": "https://cdn.arteza.ai/gen/abc123.png",
      "width": 2048,
      "height": 2048,
      "seed": 42871
    }
  ],
  "credits_used": 8,
  "credits_remaining": 1042
}

Adresy URL obrazów są ważne przez 24 godziny. Pobierz i zapisz obrazy od razu, jeśli potrzebujesz do nich stałego dostępu.

Chcesz takich szczegółów? Wypróbuj Seedream v4.5 za darmo →

Gotowy, żeby zacząć integrację? Pobierz swój klucz API →

Obsługa błędów

API zwraca standardowe kody statusu HTTP:

Przykładowa odpowiedź z błędem:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits for this request",
    "credits_required": 8,
    "credits_available": 3
  }
}

Zawsze implementuj obsługę błędów i ponowne próby dla błędów 429 i 500. Nie ponawiaj żądań dla błędów 400 i 401, te wymagają naprawy samego żądania.

Dobre praktyki dla zastosowań produkcyjnych

Limity żądań

Domyślne limity żądań zapewniają rozsądną przepustowość produkcyjną. Jeśli potrzebujesz wyższych limitów, skontaktuj się z pomocą techniczną, podając szczegóły swojego przypadku użycia.

Zastosuj wykładnicze opóźnienie dla błędów 429:

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return generate_image(prompt)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Przekroczono maksymalną liczbę prób")

Zarządzanie kredytami

Monitoruj pole credits_remaining w każdej odpowiedzi. Ustaw alerty, gdy saldo spadnie poniżej określonego progu, abyś mógł doładować konto, zanim produkcyjny ruch wyczerpie kredyty.

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Ostrzeżenie o niskim stanie kredytów: {remaining} kredytów')

Obsługa asynchroniczna

W aplikacjach skierowanych do użytkowników traktuj generowanie obrazów jako operację asynchroniczną. Nie blokuj wątku UI wywołaniem API trwającym 5-15 sekund. Możliwe podejścia:

• Natychmiast zwróć identyfikator zadania, odpytuj o status do momentu ukończenia
• Używaj webhooków (jeśli są obsługiwane) do powiadomień o zakończeniu
• Generuj spekulatywnie w tle i buforuj wyniki

Pamięć podręczna

Generowane obrazy są deterministyczne dla tego samego promptu i seeda. Agresywnie buforuj wyniki według skrótu promptu, aby uniknąć ponownego generowania identycznych obrazów.

import hashlib

def prompt_cache_key(prompt, width, height, seed):
    raw = f'{prompt}|{width}x{height}|{seed}'
    return hashlib.sha256(raw.encode()).hexdigest()

Bezpieczeństwo promptów

Jeśli twoja aplikacja udostępnia prompty użytkownikom końcowym, zaimplementuj filtrowanie treści przed wysłaniem do API. Arteza stosuje zasady dotyczące treści: prompty, które je naruszają, będą zwracać błędy, marnując kredyty i powodując problemy widoczne dla użytkowników.

Cennik dla użytkowników API

Korzystanie z API pobiera środki z salda kredytowego konta według tej samej stawki co korzystanie z wersji webowej.

Kredyty pochodzą z tego samego poziomy cenowe niezależnie od tego, czy korzystasz z nich przez stronę webową, czy przez API:

• Starter: $5 = 60 kredytów miesięcznie = 60 obrazów
• Creator: $25 = 300 kredytów miesięcznie = 300 obrazów
• Pro: $50 = 700 kredytów miesięcznie = 700 obrazów
• Studio: $120 = 1 800 kredytów miesięcznie = 1 800 obrazów

Klienci o większym wolumenie mogą skontaktować się z pomocą techniczną w sprawie cennika dla stałego użycia powyżej 100 000 obrazów miesięcznie.

Łączenie z innymi modelami Arteza

Twoja aplikacja może używać wielu modeli Seedance przez to samo API, zmieniając parametr model:

• seedream-v4-5 - 1 kredytów - jakość flagowa
• seedream-v3 - 1 kredyt - szybszy, prostszy
• seedream-5-lite - 1 kredyt - tryb głębokiego myślenia
• seedream-5-edit - 1 kredyt - edycja obrazów
• seedance-2 - generowanie wideo (inny endpoint)

Dla aplikacji, które oprócz generowania potrzebują możliwości edycji, seedream-5-edit obsługuje edycję obrazów opartą na tekście. Szczegóły znajdziesz w Dokumentacja Seedream 5 Edit.

Kwestie bezpieczeństwa

Nigdy nie ujawniaj kluczy API po stronie klienta. Zawsze przekierowuj wywołania API przez swój backend. Ujawnione klucze mogą zostać użyte do wyczerpania salda kredytowego.

Regularnie rotuj klucze. Jeśli klucz zostanie naruszony, unieważnij go i wygeneruj nowy.

Rejestruj żądania na potrzeby debugowania. Umieszczaj identyfikatory żądań w logach, aby móc powiązać błędy z odpowiedziami API.

Implementuj limity użycia na użytkownika. Jeśli twoja aplikacja oferuje generowanie AI jako funkcję, ogranicz zużycie na użytkownika, aby zapobiec nadużyciom.

Często zadawane pytania

Czy jest bezpłatny poziom dla API? Twoje 10 kredytów za rejestrację działa przy wywołaniach API. To 10 darmowych generowań Seedream v4.5 do przetestowania integracji przed opłaceniem.

Jaki jest typowy czas odpowiedzi? 5-15 sekund dla Seedream v4.5 w zależności od rozdzielczości i aktualnego obciążenia.

Czy mogę używać API w produktach komercyjnych? Tak. Użycie komercyjne jest uwzględnione. Obrazy wygenerowane przez twoich klientów są ich własnością i mogą być wykorzystywane do wszelkich legalnych celów.

Czy jest dostępne SDK dla Pythona? Oficjalne SDK są w trakcie tworzenia. Obecne REST API działa sprawnie ze standardowymi bibliotekami HTTP w dowolnym języku.

Jak obsługiwać błędy dotyczące zasad treści? Zaimplementuj komunikaty dla użytkowników informujące, że prompt został odrzucony. Rejestruj konkretny błąd na potrzeby debugowania.

Co się stanie, jeśli kredyty skończą się w trakcie żądania? API zwraca błąd 402 przed rozpoczęciem generowania. Częściowe naliczenia nigdy nie mają miejsca: albo otrzymujesz pełny obraz, albo błąd.

Czy mogę wsadowo przetwarzać wiele promptów w jednym żądaniu? Nie bezpośrednio. Użyj num_images: 6, aby uzyskać warianty tego samego promptu, lub wykonuj równoległe wywołania API dla różnych promptów.

---

API Seedream v4.5 zapewnia produkcyjne generowanie obrazów AI przy przewidywalnych kosztach za obraz i zgodnie ze standardowymi konwencjami REST. W przypadku większości integracji możesz przejść od klucza API do pierwszego działającego generowania w mniej niż 10 minut. W razie pytań lub w sprawie cennika dla dużych wolumenów skontaktuj się przez panel konta.

Zacznij integrację już dziś. Pobierz swój klucz API → | Zobacz pełny cennik → | Przeczytaj przewodnik po v4.5 →