Come usare recraft-v4.1/text-to-image tramite l'API HiAPI: guida per curl e Python

Cosa offre questo endpoint

recraft-v4.1/text-to-image è un endpoint di un modello text-to-image: invii nel corpo della richiesta un prompt testuale e alcune opzioni di modellazione, e ricevi in risposta i dati dell'immagine generata. È ideale quando vuoi produrre un'immagine finita con una sola chiamata, senza dover orchestrare tu stesso una pipeline a più passaggi.

Su HiAPI, questo modello è incluso nella modalità aggregata: un unico URL di base, un'unica intestazione di autenticazione e una struttura di richiesta/risposta coerente tra gli endpoint. Non devi integrare SDK e set di credenziali separati per ogni modello di immagine che vuoi valutare: basta puntare il client all'endpoint recraft-v4.1/text-to-image su HiAPI e il resto del codice resta stabile. Questo è particolarmente importante in fase di prototipazione, quando vuoi confrontare prompt, stili e modelli senza riscrivere ogni volta il livello di trasporto.

Un modo pratico per comprendere la chiamata:

• Prompt — la descrizione in linguaggio naturale dell'immagine che desideri.
• Style — campo del corpo della richiesta che guida il trattamento visivo dell'output.
• Resolution — campo del corpo della richiesta che determina le dimensioni dell'output.

Poiché tutti e tre viaggiano nello stesso corpo JSON, l'ingegneria del prompt e la modellazione dell'output si completano in un'unica andata e ritorno. Se ti stai chiedendo se questo sia l'endpoint giusto, la risposta di solito è sì: quando hai bisogno di una generazione di immagini sincrona e guidata dal prompt, e vuoi tenere i dettagli della pipeline dei fornitori fuori dal codice applicativo.

Prerequisiti e autenticazione

Prima della prima chiamata, assicurati di avere:

• Un account HiAPI e una chiave API. Tienila fuori dal controllo del codice sorgente e caricala da una variabile d'ambiente.
• curl per un rapido smoke test, e Python 3 con requests installato (se intendi usare gli esempi Python).
• Un prompt che desideri davvero rendere — anche grezzo basta per verificare che il collegamento sia corretto.

L'autenticazione di HiAPI si basa sulle intestazioni. La chiave API viene trasmessa tramite intestazione, con lo stesso schema di intestazione che usi sia da curl, sia da Python, sia da qualsiasi altro client HTTP. La selezione del modello avviene tramite il percorso dell'endpoint, quindi l'intestazione di autenticazione resta invariata quando cambi modello.

Una configurazione locale sicura è la seguente:

export HIAPI_API_KEY="your-key-here"

Poi fai riferimento a $HIAPI_API_KEY nei comandi della shell e a os.environ["HIAPI_API_KEY"] in Python. Non codificare mai la chiave direttamente in script che potrebbero essere committati, ed evita di incollarla nei log o nelle segnalazioni di errore. Se la chiave viene compromessa, ruotala nelle impostazioni dell'account invece di cercare di rimuoverla dalla cronologia.

Gli esempi seguenti presuppongono due cose: l'URL di base dell'API HiAPI e il percorso del modello recraft-v4.1/text-to-image. Prima di collegare il tutto alla tua build, verifica entrambi confrontandoli con il riferimento API del tuo account, poiché l'host e il percorso esatti sono le uniche cose in questa guida che dovresti copiare dalla documentazione corrente anziché dalla memoria.

Richiesta curl eseguibile

Il modo più rapido per verificare che chiave, endpoint e struttura del payload funzionino è una chiamata curl. La richiesta invia un corpo JSON contenente il prompt e i campi di modellazione, e trasmette la chiave API nell'intestazione:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Alcuni aspetti da notare in questa chiamata:

• Percorso dell'endpoint. Il nome del modello è nel percorso. Passare in seguito a un altro modello significa modificare quel segmento del percorso, non ricostruire la richiesta.
• Corpo, non stringa di query. prompt, style e resolution vanno tutti nel corpo JSON. Così l'URL resta stabile e il payload è facile da registrare e riprodurre.
• Autenticazione tramite intestazione. L'intestazione Authorization trasporta la chiave; Content-Type deve essere application/json.

Se al primo tentativo ricevi una risposta diversa da 200, controlla in questo ordine: se la chiave è impostata nella shell, se l'URL di base non ha una barra finale duplicata, se il corpo JSON è valido (le virgole finali sono spesso il colpevole). Una volta che la chiamata funziona, salva il comando esatto in un file di bozza: una chiamata curl che sai funzionare è il tuo riferimento per confrontare ogni modifica a SDK e client.

La stessa richiesta in Python

Per il codice reale, incapsula la chiamata in una piccola funzione, così che retry, logging e cambio di modello abbiano un unico posto dove risiedere. Usa requests:

import os
import requests

HIAPI_BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Punti di progettazione da conservare:

• Usa json= invece di data=. Passare un dict a json= imposta il content type e serializza il corpo per te, così il payload è identico byte per byte alla versione curl.
• Timeout esplicito. La generazione di immagini non è istantanea; un timeout generoso evita falsi errori su richieste lente ma sane. Non affidarti ai valori predefiniti del client.
• Prima raise_for_status(). Converti gli errori HTTP in eccezioni prima di tentare di leggere il corpo della risposta, così un 4xx o 5xx non viene mai scambiato per dati immagine.
• Configurazione guidata dall'ambiente. Sia l'URL di base sia la chiave provengono dall'ambiente, il che rende la funzione portabile tra locale, staging e produzione.

La funzione restituisce il JSON analizzato. Come estrarre l'immagine da quel JSON è l'argomento successivo, ed è il punto in cui la maggior parte delle integrazioni fallisce.

Gestire la risposta sincrona dell'immagine

recraft-v4.1/text-to-image restituisce i dati dell'immagine in modo sincrono: l'immagine viene restituita nella stessa risposta HTTP della richiesta, senza cicli di polling e senza ID di attività da monitorare. Questo semplifica il client, ma trasferisce due responsabilità al tuo codice: decodificare il payload e gestire esplicitamente gli errori.

Il percorso di gestione robusto è il seguente:

1. Controlla lo stato prima dell'analisi. Tratta qualsiasi risposta diversa da 200 come errore e mostra il corpo della risposta, che di solito spiega qual è il problema.
2. Leggi il campo dell'immagine in modo consapevole. Il JSON di risposta trasporta i dati dell'immagine; a seconda del campo ricevuto, può essere un URL o byte immagine codificati. Gestisci entrambi i percorsi, invece di presumere l'uno o l'altro.
3. Decodifica in modo difensivo. Se il payload è codificato in base64, decodificalo e scrivi i byte su file. Non instradare dati binari attraverso percorsi solo testuali, e non stamparli nel terminale.
4. Limita la dimensione del payload. Le risposte sincrone delle immagini sono molto più grandi del JSON tipico. Scrivi su disco in streaming dove il client lo supporta, ed evita di tenere più risposte contemporaneamente in memoria.

Passaggio minimo di salvataggio per un payload base64:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Due modalità di errore meritano una gestione dedicata. I timeout dovrebbero essere ritentati con backoff, ma solo se si prevede idempotenza — rigenerare un'immagine produce risultati diversi, quindi registra il prompt a ogni tentativo. Gli errori del client (come corpo della richiesta malformato o valori di opzione non validi) non si risolvono con i retry; fallisci rapidamente e registra il testo della risposta. Infine, verifica che il campo dell'immagine esista prima di decodificare, così un cambiamento di schema o un payload di errore genera un'eccezione chiara invece di un errore di decodifica confuso.

Adattare stile e risoluzione al tuo caso d'uso

style e resolution sono i due campi del corpo della richiesta che influenzano maggiormente il risultato restituito, ed entrambi hanno un costo di iterazione basso perché viaggiano insieme al prompt.

Style

style guida il trattamento visivo dell'output. Usalo per mantenere uno stile coerente in una serie di immagini — ad esempio, fissando lo stesso stile per un lotto di illustrazioni di prodotto o di immagini di copertina di articoli, così che sembrino un insieme. Quando il risultato non ti convince, controlla prima se lo stile è adatto al contenuto: applicare uno stile pensato per l'illustrazione a un prompt realistico crea conflitto con il testo. Prima di aggiungere dettagli, prova prompt semplici con uno stile fisso, così puoi capire se un risultato scadente dipende dallo stile o dalla formulazione.

Resolution

resolution determina le dimensioni dell'output. Falla corrispondere all'uso previsto: per avatar e miniature scegli dimensioni vicine al quadrato, per banner e immagini principali scegli dimensioni più larghe. Due regole pratiche:

• Meglio generare che ingrandire. Genera direttamente un'immagine vicina alle dimensioni finali di visualizzazione, invece di generare una miniatura e poi ingrandirla.
• Attenzione al rapporto d'aspetto. Se il tuo layout prevede un rapporto specifico, scegli una risoluzione che corrisponda a quel rapporto, invece di ritagliare a posteriori.

Diagnosticare output inattesi

Quando un'immagine non sembra giusta, isola una variabile alla volta. Mantieni il prompt invariato e cambia style; poi mantieni invariati entrambi e cambia resolution. Se nulla funziona, riscrivi il prompt con sostantivi concreti e indicazioni di composizione chiare, invece di aggiungere aggettivi. Verifica anche di non stare inviando silenziosamente tipi di valore errati — una stringa di stile che non corrisponde alle opzioni accettate potrebbe essere rifiutata o ignorata, a seconda della logica di validazione. Registra il corpo esatto della richiesta a ogni chiamata; è l'unica traccia affidabile di come è stata prodotta una determinata immagine.

Incapsulare per la produzione

Il valore della piccola funzione precedente emerge quando la irrobustisci. Un wrapper di livello produttivo dovrebbe fare quattro cose:

• Incapsulare il trasporto. Una funzione possiede URL, intestazioni, struttura del payload e timeout. I chiamanti passano solo il prompt e le opzioni, nient'altro.
• Aggiungere retry con backoff. Ritenta un numero limitato di volte su timeout e risposte 5xx; non ritentare mai gli errori 4xx. Poiché la generazione di immagini non è idempotente, mantieni basso il limite di retry e associa il prompt a ogni tentativo.
• Registrare la richiesta, non solo il risultato. Registra prompt, stile, risoluzione, stato e durata. Quando qualcuno chiede perché un'immagine è così, quel log è la risposta.
• Trattare il modello come parametro. Passa il percorso del modello come parametro, con valore predefinito recraft-v4.1/text-to-image. Così passare a un altro modello di immagine diventa una modifica di configurazione anziché un refactoring, rendendo economica la valutazione affiancata.

Mantieni il wrapper leggero. Resisti alla tentazione di aggiungervi cache, accodamento o politiche di archiviazione — appartengono a un livello superiore, così possono evolvere indipendentemente dalla chiamata API. Un'interfaccia stabile significa anche che i tuoi test possono simulare il livello di trasporto e verificare il payload che invierai, il che intercetta la maggior parte degli errori di integrazione prima che raggiungano una richiesta reale.

Con autenticazione, una richiesta che sai funzionare e una gestione esplicita della risposta, hai tutto il necessario per chiamare recraft-v4.1/text-to-image da HiAPI con curl e Python, e potrai in seguito cambiare modello senza toccare il resto del codice.