Vai al contenuto principale
Questo documento introduce una spiegazione per l’integrazione dell’API per la produzione di foto identificative AI, che consente di creare vari stili di foto identificative inserendo l’URL di una foto del soggetto e il modello preferito.

​
Processo di richiesta

Per utilizzare l’API, è necessario prima andare alla pagina corrispondente dell’API per la produzione di foto identificative AI per richiedere il servizio corrispondente. Una volta entrati nella pagina, cliccare sul pulsante “Acquire”, come mostrato nell’immagine: Se non si è ancora effettuato il login o la registrazione, si verrà automaticamente reindirizzati alla pagina di login per registrarsi e accedere. Dopo aver effettuato il login o la registrazione, si tornerà automaticamente alla pagina corrente. Alla prima richiesta, verrà offerto un credito gratuito, che consente di utilizzare l’API senza costi.

​
Utilizzo di base

Innanzitutto, è importante comprendere il modo di utilizzo di base, che consiste nell’inserire l’immagine del soggetto da elaborare e il modello di foto identificativa AI preferito, per ottenere il risultato elaborato. È necessario innanzitutto passare un campo image_urls, che è un array di link all’immagine del soggetto da elaborare, come mostrato nell’immagine:

Dopodiché, è necessario inserire il modello preferito. Questo documento fornisce otto modelli popolari, i dettagli dei modelli possono essere consultati qui di seguito: 
{
   "male_portrait":  Foto maschile
   "male_portrait2":  Foto maschile (un'altra versione)
   "kindergarten":  Foto di iscrizione all'asilo
   "logo_tshirt": Foto con logo aziendale su T-shirt
   "wedding":  Foto di registrazione matrimonio
   "business_photo":  Foto professionale
   "bob_suit": Foto con abito nero e taglio bob
   "female_portrait":  Foto femminile
}
Successivamente, possiamo anche specificare il parametro di velocità di generazione mode, che è generalmente diviso in due tipi: lento relax e veloce fast, i dettagli sono i seguenti:

Possiamo vedere che qui abbiamo impostato le intestazioni della richiesta, che includono:
  • accept: il formato della risposta desiderata, qui è impostato su application/json, ovvero formato JSON.
  • authorization: la chiave per chiamare l’API, che può essere selezionata direttamente dopo la richiesta.
Inoltre, abbiamo impostato il corpo della richiesta, che include:
  • mode: il canale per generare la foto identificativa, principalmente ci sono due tipi: fast (veloce) e relax (lento). Quando si utilizza relax, si consiglia vivamente di utilizzare il parametro callback_url qui sotto.
  • template: lo stile del modello della foto identificativa.
  • image_urls: i link delle immagini del soggetto da caricare.
  • callback_url: l’URL per ricevere il risultato.
Dopo aver effettuato la selezione, possiamo notare che a destra è stato generato il codice corrispondente, come mostrato nell’immagine:

Cliccando sul pulsante “Try” è possibile effettuare un test, come mostrato nell’immagine sopra, e abbiamo ottenuto il seguente risultato: 
{
  "success": true,
  "task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
  "data": [
    {
      "id": "202411031951124776",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto maschile"
    },
    {
      "id": "202411031951128490",
      "image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
      "template": "Foto maschile"
    }
  ]
}
Il risultato restituito contiene diversi campi, descritti di seguito:
  • success: lo stato attuale del compito di generazione della foto identificativa.
  • task_id: l’ID del compito di generazione della foto identificativa.
  • data: l’elenco dei risultati del compito di generazione della foto identificativa.
    • id: l’ID della foto del compito di generazione della foto identificativa.
    • image_url: il link all’immagine del compito di generazione della foto identificativa.
    • template: il nome del modello della foto identificativa del compito di generazione.
Possiamo vedere che abbiamo ottenuto informazioni soddisfacenti sulla foto identificativa in base al modello e all’immagine del soggetto. Dobbiamo solo ottenere la foto identificativa dal link dell’immagine presente nel campo data. Inoltre, se si desidera generare il codice di integrazione corrispondente, è possibile copiarlo direttamente, ad esempio il codice CURL è il seguente: 
curl -X POST 'https://api.acedata.cloud/headshots/generate' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "mode": "fast",
  "template": "male_portrait",
  "image_urls": ["https://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"]
}'

​
Callback asincrona

Poiché il tempo di generazione della foto identificativa AI è relativamente lungo, circa 1-2 minuti, 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, deve specificare un campo callback_url. Dopo che il client ha avviato 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 della generazione della foto identificativa 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 associato tramite l’ID. Di seguito, attraverso un esempio, vediamo come operare concretamente. Innanzitutto, il callback Webhook è un servizio in grado di ricevere richieste HTTP, e 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 si ottiene un URL Webhook, come mostrato nell’immagine: Copiare questo URL per utilizzarlo come Webhook, l’esempio qui è https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a. Successivamente, possiamo impostare il campo callback_url su questo URL Webhook, insieme a inserire il link all’immagine del soggetto e il modello. Questo documento consiglia di utilizzare il callback asincrono quando il parametro mode è impostato su relax, i dettagli sono mostrati nell’immagine:

Cliccando su “Esegui”, possiamo notare che riceviamo immediatamente un risultato, come segue: 
{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
Dopo un momento, possiamo osservare il risultato della generazione della foto su https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a, come mostrato nell’immagine: Il contenuto è il seguente: 
{
    "success": true,
    "task_id": "763b1450-8804-434f-acc7-d713be73a28f",
    "data": [
        {
            "id": "202411032010131366",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "Foto di profilo maschile"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "Foto di profilo maschile"
        }
    ]
}
Si può vedere che nel risultato c’è un campo task_id, gli altri campi sono simili a quelli sopra, attraverso questo campo è 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 compreso come utilizzare l’API per la creazione di foto di identificazione AI, che può realizzare vari stili di foto di identificazione inserendo l’URL della foto del volto e il template preferito. 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.