HiAPI
It
Blog

Tutoriale

Come usare seedream-5.0-flash tramite l'API hiapi: curl, Python e richieste eseguibili

Oct 8, 2026
Come usare seedream-5.0-flash tramite l'API hiapi: curl, Python e richieste eseguibili

Cosa costruirai

Un'integrazione funzionante che chiama il modello di immagini seedream-5.0-flash di hiapi da curl e Python: invia una richiesta di generazione testo-immagine (o di modifica immagine), esegui il polling del risultato e scarica l'URL di output. Alla fine avrai uno script pronto da inserire nel tuo progetto.

Prerequisiti

  • Un account hiapi e una chiave API. Ottienila dalla console hiapi — la chiave ha la forma sk-....
  • curl o Python 3.8+ (pip install requests).
  • Nessuna libreria di editing immagini necessaria — seedream-5.0-flash accetta un semplice prompt, oppure un prompt più un URL di immagine di input per l'editing.

Riferimento completo del modello: seedream-5.0-flash su hiapi e la pagina della documentazione API.

Esempio minimo eseguibile

hiapi espone tutti i modelli di generazione tramite un unico endpoint: prima crei un task, poi ne esegui il polling (o ricevi una callback) fino al completamento.

curl

# 1. 创建任务
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {
      "prompt": "a minimalist ceramic teapot on a wooden table, soft morning light, product photography",
      "size": "2K"
    }
  }'
# => {"code":0,"data":{"taskId":"task_xxx","status":"pending", ...}}

# 2. 轮询直到完成
curl -s https://api.hiapi.ai/v1/tasks/task_xxx \
  -H "Authorization: Bearer sk-<your-api-key>"
# => {"code":0,"data":{"taskId":"task_xxx","status":"success",
#      "output":[{"url":"https://...signed-url...","expireAt":"..."}]}}

Python

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def generate_image(prompt: str, size: str = "2K") -> str:
    create = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "seedream-5.0-flash", "input": {"prompt": prompt, "size": size}},
        timeout=30,
    )
    create.raise_for_status()
    task_id = create.json()["data"]["taskId"]

    while True:
        poll = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        poll.raise_for_status()
        data = poll.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task failed: {data}")
        time.sleep(2)


if __name__ == "__main__":
    image_url = generate_image("a minimalist ceramic teapot on a wooden table, soft morning light")
    print(image_url)

Note sull'oggetto input:

  • prompt (obbligatorio, 1–5000 caratteri) — cosa generare, oppure cosa modificare se passi anche image.
  • image (opzionale, stringa o array di massimo 10 URI URL/base64 data:image/...) — passa questo parametro per modificare/usare come riferimento un'immagine esistente invece di generare da zero. Omettilo per la generazione puramente testo-immagine.
  • size (opzionale, predefinito "2K") — uno dei preset 1K / 1.5K / 2K, oppure una stringa personalizzata WIDTHxHEIGHT come "1536x1024" (pixel totali 921.600–4.624.220, rapporto d'aspetto tra 1:16 e 16:1).
  • output_format (opzionale) — "jpeg" o "png".
  • background (opzionale, predefinito "opaque") — imposta "transparent" solo quando modifichi un'immagine con canale alpha.

Il campo output[].url nella risposta è un link firmato e soggetto a scadenza (campo expireAt) — scaricalo o ri-ospitalo per tempo invece di conservare a lungo questo hotlink.

Modalità per la produzione

Usare le callback invece del polling

Per integrazioni server-to-server, salta il polling e lascia che hiapi ti notifichi al completamento del task. Aggiungi un oggetto callback di primo livello accanto a model/input (non annidato dentro input):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-flash",
    "input": {"prompt": "a minimalist ceramic teapot on a wooden table"},
    "callback": {"url": "https://yourapp.example.com/hooks/hiapi", "when": "final"}
  }'

when: "final" è attualmente l'unico valore supportato — quando il task raggiunge uno stato terminale (success o fail), il tuo endpoint riceve esattamente una POST. Per prevenire tentativi di consegna ripetuti, deduplica per taskId e, prima di affidarti a questa modalità in produzione, verifica che il tuo endpoint sia raggiungibile via HTTPS.

Polling vs. callback

  • Usa il polling quando fai prototipazione, esegui script di breve durata o non hai ancora un endpoint HTTPS pubblico. Semplice, ma aumenta la latenza e il volume di richieste per i task lenti.
  • Usa le callback quando esegui un servizio — nessuna richiesta di polling sprecata, sai immediatamente quando un task è completo. Richiede un URL HTTPS pubblicamente accessibile.

Idempotenza

La generazione di immagini non è di per sé idempotente (lo stesso prompt non restituisce due volte la stessa immagine), quindi se il tuo flusso di lavoro richiede una semantica di "retry senza doppio addebito", traccia il taskId dalla tua parte e, dopo un timeout, controlla lo stato del task prima di inviare di nuovo la stessa richiesta, invece di riprovare alla cieca.

Gestione degli errori

  • 401 con permission_denied — la tua chiave API è mancante, malformata o revocata:

    {"error":{"code":"permission_denied","message":"This API key is invalid. Check that it is correct or use another API key and try again.","type":"hiapi_error"}}

    Verifica attentamente di inviare Authorization: Bearer sk-... (e non solo la chiave grezza) e che la chiave non sia stata ruotata.

  • 400 con INVALID_REQUEST — un campo non ha superato la validazione. Il message ti dice esattamente quale campo e perché, ad esempio un size fuori intervallo. Correggi quel campo e reinvia; non riprovare così com'è.

  • Fallimento a livello di task — la chiamata HTTP può riuscire (200) mentre il task termina comunque con status: "fail" dopo l'elaborazione. Controlla sempre data.status nella risposta di polling/callback, non solo il codice di stato HTTP della chiamata di creazione.

Link interni correlati

Domande frequenti

seedream-5.0-flash è gratuito? No — viene addebitato per immagine tramite la tua chiave API hiapi. Consulta la pagina dei prezzi per le tariffe correnti; senza una chiave valida non è possibile l'accesso in produzione.

seedream-5.0-flash supporta la modifica immagine-immagine, non solo testo-immagine? Sì. Aggiungi il campo image accanto a prompt (URL o stringa base64 data:image/..., oppure un array di massimo 10), e il modello modificherà/fonderà in base all'immagine di riferimento invece di generare da zero.

Perché la mia richiesta restituisce 200 ma nessuna immagine? POST /v1/tasks che restituisce 200 significa solo che il task è stato accettato — la generazione è asincrona. Esegui il polling di GET /v1/tasks/<id> (o attendi la callback) e controlla data.status; l'URL dell'immagine compare solo quando status è "success".

Posso richiedere una risoluzione personalizzata invece di 1K/1.5K/2K? Sì — passa size come "WIDTHxHEIGHT" (ad esempio "1536x1024") invece del preset. I pixel totali devono essere tra 921.600 e 4.624.220 e il rapporto d'aspetto tra 1:16 e 16:1, altrimenti la richiesta restituisce 400.

Cosa succede all'URL di output dopo un po' di tempo? L'output[].url restituito è un URL firmato con timestamp expireAt — non è archiviazione permanente. Dopo il successo del task, scarica i byte o copiali nel tuo storage il prima possibile.

La mia callback non si è mai attivata — cosa devo controllare per primo? Verifica che il tuo callback.url sia un endpoint HTTPS pubblicamente accessibile (non localhost o un indirizzo solo interno) e che callback sia un campo di primo livello nel corpo della richiesta — non annidato dentro input.

TagseedreamGenerazione di immaginiTutorial APIpythoncurl

Articoli correlati

Vedi tutti gli articoli →

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API