Come usare flux-1.1-pro tramite l'API HiAPI: curl, Python e richieste eseguibili

Cosa offre flux-1.1-pro prima ancora che tu scriva una riga di codice

flux-1.1-pro è un modello di generazione di immagini da testo, richiamabile tramite HiAPI.ai come endpoint gestito. Invii il prompt e i parametri di generazione in formato JSON e ricevi indietro l'immagine generata. Non serve installare nulla, né ospitare autonomamente i pesi del modello, né gestire risorse GPU. La tua superficie di integrazione è un endpoint HTTP, più le credenziali per l'autenticazione.

Per uno sviluppatore questo significa che, prima ancora di scrivere la prima riga di codice, ci sono tre aspetti che orientano il tuo design.

Primo, la richiesta è JSON in ingresso, immagine in uscita. Il prompt, le proporzioni e qualche parametro di controllo risiedono nel corpo della richiesta. La risposta trasporta i dati dell'immagine o un riferimento ad essi, a seconda del metodo di consegna dell'attività. Tratta il corpo della richiesta come un contratto e centralizzalo in un unico punto, così i due percorsi curl e Python non potranno mai divergere.

Secondo, rispetto a una normale chiamata API, la generazione di immagini è un'operazione lenta. Qualche secondo è normale; prompt complessi ad alta risoluzione possono richiedere di più. Qualunque chiamante in produzione deve dare per scontata la latenza e pianificarla, invece di trattare la chiamata come una lettura da database.

Terzo, la qualità dell'output dipende principalmente dal prompt, non dal cablaggio. L'integrazione è la parte semplice. Il vero lavoro sta nel descrivere con precisione ciò che vuoi e nel validare la tua ricetta con output reali prima di andare in produzione.

Tenendo a mente questi tre punti, il resto della guida è un processo meccanico: costruire la richiesta, verificare che funzioni, trasferirla, quindi consolidarla e ottimizzarla. Dall'inizio alla fine, tutto passa attraverso l'API HiAPI: una sola credenziale, un solo URL di base, una sola struttura JSON da imparare.

La tua prima richiesta curl

Inizia con curl. Elimina ogni livello di astrazione tra te e l'endpoint, così quando qualcosa fallisce sai che il problema è nel corpo della richiesta, non nel tuo framework.

Una chiamata minima contiene tre parti: l'endpoint, l'header di autenticazione e il corpo JSON della richiesta.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "prompt": "a ceramic coffee mug on a weathered wooden table, soft morning window light, shallow depth of field, product photography",
    "aspect_ratio": "1:1"
  }'

Leggi il corpo della richiesta campo per campo:

• model specifica il modello che vuoi usare. Scrivilo esplicitamente, così eventuali modifiche future ai valori predefiniti non altereranno mai silenziosamente il tuo output.
• prompt è la descrizione in linguaggio naturale. Qui risiede quasi tutto il tuo budget di qualità.
• aspect_ratio controlla l'inquadratura. Scegliilo intenzionalmente, invece di affidarti a un valore predefinito che non hai verificato.

Metti la chiave in una variabile d'ambiente (HIAPI_API_KEY), invece di incollarla direttamente nel comando. Questa abitudine si trasferirà direttamente in Python e in qualsiasi passo CI aggiungerai in seguito.

Quando la chiamata riesce, ottieni una risposta JSON che descrive l'immagine completata. Prima di chiudere il terminale, esaminala e individua il riferimento o i dati dell'immagine. Quando la chiamata fallisce, ottieni un corpo di errore con codice di stato e messaggio; leggi il messaggio alla lettera, perché un formato di campo errato è la causa più comune dei primi fallimenti.

Un avvertimento che ti farà risparmiare un'ora: non incollare nella shell prompt multiriga con virgolette non escapate. Per qualsiasi cosa più lunga di una frase breve, usa un heredoc o un file.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Quel request.json è l'artefatto che dovresti versionare. È l'unica fonte di verità del corpo della richiesta, e la sezione successiva lo riutilizzerà così com'è.

Trasferire la stessa chiamata in Python

L'obiettivo del trasferimento non è scrivere nuova logica, ma inviare esattamente lo stesso corpo JSON della richiesta. Carica lo stesso request.json, così i due percorsi non potranno divergere.

import json
import os

import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"

with open("request.json") as f:
    payload = json.load(f)

response = requests.post(
    API_URL,
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

if response.status_code != 200:
    print(response.status_code)
    print(response.text)
    response.raise_for_status()

print(response.json())

Qui ci sono tre dettagli importanti.

L'header di autenticazione e gli header della richiesta sono lo stesso insieme. Usare json=payload fa sì che requests serializzi il corpo e imposti il tipo di contenuto al posto tuo; scrivere l'header esplicitamente è innocuo e documenta l'intento.

Imposta un timeout. Non lasciare mai una richiesta di generazione appesa a un valore predefinito illimitato. Un timeout esplicito e generoso va bene: l'importante è che sia esplicito.

Controlla il corpo dell'errore prima di sollevare l'eccezione. Se esegui prima raise_for_status(), questo scarterà il corpo della risposta dai tuoi log. Stampa prima codice di stato e testo, poi solleva. Quando un campo viene rifiutato, avrai bisogno di quel testo.

Se stai adottando un client HTTP asincrono, la struttura non cambia: stesso URL, stessi header, stesso corpo, solo await client.post(...) con lo stesso timeout. Il contratto del corpo della richiesta è costante; il client è un dettaglio implementativo.

Tieni il corpo della richiesta fuori dal codice sorgente Python. Quando una ricetta di prompt funziona, dovrebbe appartenere a un file o a una riga di database, non a una stringa letterale sepolta in una funzione, così potrai farne il diff e rieseguirla.

Gestire attività asincrone senza bloccare la tua applicazione

Tratta la generazione come un'attività, non come una chiamata di funzione. Che il tuo percorso di consegna sembri sincrono o restituisca un'attività che devi interrogare, la conseguenza pratica è la stessa: la tua applicazione non deve mai occupare un thread di richiesta illimitatamente in attesa di un'immagine.

Un pattern funzionante prevede quattro passi.

1. Invia da un worker, non dalla richiesta utente

Nel livello web accetta l'azione di generazione dell'utente, persisti un record dell'attività, mettila in coda e restituisci subito. È un worker in background a eseguire la chiamata API effettiva. L'utente interroga il tuo endpoint, non il modello.

2. Limita l'attesa

Imposta per ogni tentativo un timeout scelto deliberatamente. Se la piattaforma restituisce un'attività che devi interrogare, fallo a intervalli fissi, con un numero massimo di tentativi e una scadenza calcolata dall'inizio dell'attività (non dal numero di tentativi). Preferisci un backoff moderato a un ciclo serrato.

3. Riprova solo i fallimenti che vale la pena riprovare

Riprova gli errori di trasporto, i timeout e gli errori lato server con backoff esponenziale e jitter, entro un numero limitato di tentativi. Non riprovare gli errori di validazione: un campo rifiutato o un prompt vuoto falliranno allo stesso modo ogni volta, e il retry farà solo attendere più a lungo l'utente prima che veda il messaggio reale.

4. Rendi le attività idempotenti dal tuo lato

Registra nel database il corpo esatto della richiesta e l'ID dell'attività. Se il tuo worker va in crash dopo l'invio ma prima di registrare il successo, puoi ricontrollare l'attività invece di reinviarla ciecamente. Quando devi reinviare, aggiungi una breve chiave di deduplicazione lato client, così un guasto temporaneo non accoda tre generazioni identiche.

import time

def poll_until_done(fetch_status, job_id, deadline_seconds=180):
    start = time.monotonic()
    delay = 2.0
    while True:
        status = fetch_status(job_id)
        if status["state"] in ("succeeded", "failed"):
            return status
        if time.monotonic() - start > deadline_seconds:
            raise TimeoutError(f"generation {job_id} exceeded deadline")
        time.sleep(delay)
        delay = min(delay * 1.5, 10.0)

Questo helper è volutamente generico: riceve una funzione che recupera lo stato, quindi lo stesso ciclo è adatto a qualsiasi endpoint basato su attività che integrerai in seguito. Le proprietà importanti sono la scadenza, il backoff limitato e il controllo dello stato terminale, non il trasporto specifico.

Costruire prompt che rendono in modo affidabile

Un prompt lungo non è un prompt migliore. La struttura è ciò che conta. Uno scheletro ripetibile ti dà risultati coerenti e, quando qualcosa va storto, un punto in cui modificare una sola variabile alla volta.

Usa quattro slot in quest'ordine:

1. Soggetto: cosa c'è nell'immagine, in modo specifico. "Una tazza di caffè in ceramica" batte "qualcosa per un bar".
2. Stile: tono visivo: fotografia, illustrazione, acquerello, rendering 3D, scatto di prodotto. Specifica il medium e, se utile, la luce.
3. Composizione: inquadratura e camera: proporzioni, distanza di scatto, angolazione, profondità di campo, posizione del soggetto nell'inquadratura.
4. Vincoli: ciò che vuoi e non vuoi esplicitamente, in modo conciso.

[subject] a single ceramic coffee mug, matte glaze, small handle
[style] product photography, soft diffused window light, muted palette
[composition] 1:1, eye-level, subject centered, shallow depth of field, plain background
[constraints] no text, no logos, no hands

Al momento dell'invio, appiattiscilo in un unico prompt; le parentesi quadre sono per te, non per il modello. Il valore di scrivere per slot sta nel fatto che, quando l'output non è corretto, sai quale slot modificare.

Alcune regole pratiche:

• Metti il soggetto per primo. La prima clausola ha il peso maggiore.
• Preferisci nomi e aggettivi concreti alle parole astratte di atmosfera. "Smalto opaco" cambia i pixel; "sensazione premium" praticamente no.
• Metti il linguaggio della camera nello slot composizione, non in quello del soggetto. Mescolarli genera istruzioni impazienti e contraddittorie.
• Quando iteri, modifica un solo slot alla volta e conserva il testo esatto del prompt che ha prodotto l'output accettato.

Le proporzioni sono una decisione di composizione, non una toppa a posteriori. Sceglile per adattarle al punto in cui apparirà l'immagine (quadrato per una griglia, più alto per un banner hero) e adatta il resto del prompt a quella cornice.

Usare efficacemente gli elenchi di termini negativi

L'elenco di termini negativi dice al modello cosa evitare. È uno strumento affilato, utile in una gamma ristretta: ottimo per sopprimere difetti ricorrenti, pessimo come cestino in cui elencare ogni imperfezione che ti viene in mente.

I termini negativi devono essere brevi e specifici. Per la maggior parte dei prompt, da cinque a otto voci brevi sono sufficienti. Scrivi cose concrete:

no text, no watermark, no logos, no extra fingers, no harsh shadows

Questo elenco funziona perché ogni voce nomina qualcosa di visibile e verificabile. Confrontalo con negazioni vaghe come "not ugly" o "bad quality": trasportano quasi nessun segnale operativo e diluiscono le voci che contano davvero.

Dove i termini negativi aiutano davvero:

• Sopprimere difetti che vedi ripetutamente. Se mani o testo compaiono di continuo, scriverli esplicitamente è la correzione più diretta.
• Igiene legale e di brand. Escludi logo e watermark prima che l'immagine arrivi a un'interfaccia rivolta all'utente.
• Imporre sfondi puliti per scatti di prodotto o immagini vicine all'interfaccia.

Dove invece ti remano contro:

• Contraddicono il prompt positivo. "Nessuna ombra" nei negativi contro "luce laterale drammatica" nel soggetto è un conflitto che il modello risolverà in modi imprevedibili. Correggi il prompt positivo.
• Negano cose che difficilmente potrebbero comparire. Una lunga lista di fallimenti improbabili aggiunge solo rumore e non cambia il rendering.
• Usare i negativi per compensare un soggetto vago. Se il soggetto non è chiaro, nessun elenco di negativi lo salverà.

Un dettaglio pratico: alcuni client accettano i negativi come campo separato invece che come testo aggiuntivo. Verifica quale modalità supporta la tua richiesta e mantieni quel campo nel corpo della richiesta salvato, così curl e Python si comportano in modo identico.

Ricette di prompt con output reali

Le ricette seguenti sono punti di partenza, non garanzie. Il flusso onesto è: esegui la ricetta tramite la tua integrazione, guarda l'output, poi regola uno slot. Qualunque output che non hai generato tu stesso va considerato non verificato.

Ricetta 1: scatto di prodotto pulito

A single matte-black wireless earbud case on a light concrete surface,
studio product photography, soft key light from the left, 1:1, centered,
shallow depth of field, plain background. No text, no logos, no hands.

Caratteristiche attese: soggetto nitido e centrato, decadimento morbido, sfondo non disordinato. Se la superficie appare troppo elaborata, stringi "plain background" e rimuovi ogni parola relativa alla trama. Se la luce è troppo piatta, aggiungi una parola direzionale, e nient'altro.

Ricetta 2: ritratto editoriale

Portrait of a person in a wool coat, natural window light, calm expression,
3:4, chest-up framing, subject slightly off-center, muted film palette.
No text, no watermark.

Caratteristiche attese: luce direzionale morbida, colori sobri. Se l'inquadratura è più ampia del previsto, anticipa "chest-up framing" e rimuovi parole concorrenti sulla composizione.

Ricetta 3: illustrazione isometrica

Isometric illustration of a small reading nook: armchair, floor lamp, bookshelf,
flat vector style, limited palette of warm neutrals and one accent color,
1:1, centered composition, clean white background. No text, no gradients.

Caratteristiche attese: geometria nitida e riempimenti piatti. Se la palette deriva, specifica esplicitamente il colore d'accento e mantieni "clean white background" come ultima clausola, così prevarrà.

Ricetta 4: banner hero

A wide misty mountain ridge at sunrise, layered depth, minimal detail,
16:9, subject occupying the lower third, generous empty sky for overlaid text.
No text, no watermark.

Caratteristiche attese: immagine calma e povera di dettagli, con spazio negativo utilizzabile. L'espressione "overlaid text" riserva lo spazio; non rende lettere, e l'elenco di negativi tiene il testo fuori dall'immagine stessa.

Per ogni ricetta annota il corpo esatto della richiesta, le proporzioni e la data. Quando ci tornerai tra un mese, potrai rieseguire il corpo salvato e confrontarlo con l'output registrato, invece di indovinare perché il risultato è cambiato.

Errori, limiti e cosa controllare per primo

Quando una generazione fallisce o l'output non è corretto, prima di modificare il codice percorri questa checklist.

Prima controlla il corpo della richiesta

• Il corpo è JSON valido? Virgole finali o virgolette non escapate sono le cause più comuni dei primi fallimenti. Valida il tuo request.json salvato prima di inviarlo.
• I nomi dei campi sono esattamente corretti? Un parametro scritto male di solito viene rifiutato o silenziosamente ignorato. Confronta con la struttura della richiesta nella documentazione, non con la memoria.
• Il nome del modello è corretto ed esiste? Non affidarti ai valori predefiniti.
• Il prompt non è vuoto e rientra nella lunghezza prevista dalla documentazione? I limiti sono indicati nella documentazione della piattaforma; leggili lì invece di ipotizzare un numero.

Poi controlla autenticazione e trasporto

• La chiave API esiste ed è attualmente valida? Un 401 di solito significa header mancante, malformato o chiave ruotata.
• L'URL dell'endpoint e il metodo sono corretti? Un POST inviato a un percorso GET fallisce in modo che sembra un problema di chiave.
• Il tuo timeout è troppo stretto? Se il tuo client si arrende prima che l'attività sia completata, il timeout che vedi non ha nulla a che fare con il modello.

Poi controlla la struttura della richiesta

• La classe del codice di stato ti dice dove guardare. Un 4xx è quasi sempre un problema della tua richiesta; un 5xx di solito è transitorio e merita un retry limitato.
• Leggi il messaggio di errore alla lettera. Stampa il corpo della risposta prima di sollevare l'eccezione. Il campo menzionato nel messaggio è quello da correggere.
• Una risposta di rate limit o quota significa rallentare e riprovare con backoff, non riscrivere il prompt.

Infine, controlla il prompt

Se la chiamata riesce ma l'immagine non è corretta, sei nel dominio del prompt, non in quello degli errori:

• Il soggetto manca o è troppo generico? Spostalo nella prima clausola e rendilo specifico.
• La composizione non è corretta? Correggi insieme proporzioni e parole di inquadratura; non usare l'una per compensare l'altra.
• Un difetto ricorre? Aggiungi un termine negativo breve e specifico.
• C'è una contraddizione? Individua il termine negativo che contrasta il prompt positivo ed eliminalo.

Più di ogni altra cosa, mantieni un'abitudine: per ogni generazione che ti interessa, registra il corpo esatto della richiesta, lo stato della risposta e il riferimento dell'immagine generata. La riproducibilità trasforma il debug da indovinello in diff. Costruisci la tua prima richiesta, verifica l'output, poi stringi il prompt prima di andare in produzione, e conserva il corpo della richiesta usato al lancio, così la prossima modifica avrà un riferimento reale con cui confrontarsi.