Vai al contenuto principale
Il servizio di editing delle immagini di OpenAI consente di inviare un numero qualsiasi di immagini e istruzioni, restituendo le immagini modificate. Questo documento descrive principalmente il processo di utilizzo dell’API OpenAI Images Edits, che ci permette di utilizzare facilmente le funzionalità di editing delle immagini ufficiali di OpenAI.

​
Processo di Richiesta

Per utilizzare l’API OpenAI Images Edits, è possibile visitare la pagina OpenAI Images Edits API e cliccare sul pulsante “Acquire” per ottenere le credenziali necessarie per la richiesta: Se non sei ancora loggato o registrato, verrai automaticamente reindirizzato alla pagina di accesso per invitarti a registrarti e accedere; dopo aver effettuato il login o la registrazione, verrai riportato automaticamente alla pagina corrente. Alla prima richiesta, verrà fornito un credito gratuito, che consente di utilizzare gratuitamente questa API.

​
Utilizzo di Base

Successivamente, puoi utilizzare il codice per effettuare la chiamata; qui sotto è riportato un esempio di chiamata tramite CURL: 
curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Create a lovely gift basket with these this items in it'
Quando utilizzi per la prima volta questa interfaccia, è necessario compilare almeno quattro contenuti: uno è authorization, che puoi selezionare direttamente dal menu a discesa. Un altro parametro è model, che rappresenta la categoria del modello di OpenAI che scegli di utilizzare; qui abbiamo principalmente 1 tipo di modello, i dettagli possono essere consultati nei modelli forniti. Un altro parametro è prompt, che è la parola chiave che inseriamo per generare l’immagine. L’ultimo parametro è image, che richiede il percorso dell’immagine da modificare, come mostrato nell’immagine sottostante:

Ecco un esempio di codice di chiamata in Python con lo stesso effetto: 
import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Save the image to a file
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)
Per utilizzare Python, dobbiamo prima importare due variabili ambientali: una OPENAI_BASE_URL, che può essere impostata su https://api.acedata.cloud/openai, e l’altra è la variabile di credenziali OPENAI_API_KEY, il cui valore è ottenuto da authorization. Su Mac OS, puoi impostare le variabili ambientali con i seguenti comandi: 
export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}
Dopo la chiamata, noterai che verrà generata un’immagine gift-basket.png nella directory corrente, il risultato specifico è il seguente:

In questo modo abbiamo completato l’operazione di editing dell’immagine; attualmente, il compito ufficiale di Edits supporta solo due modelli: dall-e-2 e gpt-image-1.

​
Callback Asincrona

Poiché il tempo di editing delle immagini dell’API OpenAI Images Edits potrebbe essere relativamente lungo, se l’API non risponde per un lungo periodo, la richiesta HTTP manterrà la connessione, causando un consumo aggiuntivo di risorse di sistema. Pertanto, questa API offre anche supporto per callback asincroni. Il processo complessivo è: quando il client avvia la richiesta, specifica un campo callback_url aggiuntivo; dopo che il client ha effettuato la richiesta API, l’API restituirà immediatamente un risultato contenente un campo task_id, che rappresenta l’ID del compito corrente. Quando il compito è completato, il risultato dell’editing dell’immagine verrà inviato al callback_url specificato dal client in formato JSON POST, includendo anche il campo task_id, in modo che il risultato del compito possa essere correlato tramite l’ID. Di seguito, vediamo un esempio per capire come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP; gli sviluppatori dovrebbero sostituirlo con l’URL del server HTTP che hanno creato. Qui, per comodità di dimostrazione, utilizziamo un sito Web pubblico di esempio per Webhook, https://webhook.site/, aprendo questo sito otterrai un URL Webhook, come mostrato nell’immagine: Copia questo URL e puoi usarlo come Webhook; l’esempio qui è https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, riempiendo i parametri corrispondenti, come mostrato nel seguente codice: 
curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
Dopo la chiamata, puoi notare che riceverai immediatamente un risultato, come segue: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Dopo un momento, possiamo osservare il risultato dell’editing dell’immagine sull’URL Webhook, il contenuto è il seguente: 
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}
Possiamo vedere che nel risultato c’è un campo task_id, e il campo data contiene lo stesso risultato di editing dell’immagine della chiamata sincrona; tramite il campo task_id è possibile realizzare l’associazione del compito.

​
Gestione degli Errori

Quando si chiama l’API, se si verifica un errore, l’API restituirà il codice di errore e le informazioni corrispondenti. Ad esempio:
  • 400 token_mismatched: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 400 api_not_implemented: Richiesta non valida, probabilmente a causa di parametri mancanti o non validi.
  • 401 invalid_token: Non autorizzato, token di autorizzazione non valido o mancante.
  • 429 too_many_requests: Troppe richieste, hai superato il limite di frequenza.
  • 500 api_error: Errore interno del server, qualcosa è andato storto sul server.

​
Esempio di Risposta di Errore

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Conclusione

Attraverso questo documento, hai già compreso come utilizzare l’API di OpenAI Images Edits per sfruttare facilmente le funzionalità di editing delle immagini ufficiali di OpenAI. Speriamo che questo documento possa aiutarti a integrare e utilizzare meglio questa API. Se hai domande, non esitare a contattare il nostro team di supporto tecnico.