Guida rapida all'API di Imagen

  • Aggiornato

Usa la nostra guida rapida per scoprire come funziona l'API di Imagen e personalizzare il tuo flusso di lavoro.

Completa l'onboarding

Devi registrarti su Imagen, configurare il tuo ambiente, scegliere un Profilo AI e completare alcuni altri passaggi prima di usare questa guida rapida. Vedi Onboarding.

Se vuoi usare l'API di Imagen con poco codice, ecco l'SDK in Python.

1. Ottieni un elenco dei Profili AI disponibili

Ottieni un elenco dei Profili AI e delle loro chiavi. Ecco la documentazione API di riferimento per questo endpoint.

GET /v1/profiles/ 

Esempio di risposta

La risposta include i Profili AI disponibili. Ogni Profilo AI ha una profile_key che lo identifica. Ti serve questa profile_key per modificare le foto nel tuo progetto.

{

"data": {

"profiles": [

{

"profile_key": <chiave profilo del Profilo AI Personale>,

"profile_name": "matrimonio",

"profile_type": "Personal",

"image_type": "RAW"

},

{

"profile_key": 14715,

"profile_name": "LOVE & LIGHT",

"profile_type": "Talent",

"image_type": "RAW"

},

{

"profile_key": 163322,

"profile_name": "ELEGANT HOME",

"profile_type": "Talent",

"image_type": "RAW"

}

]

}

}

2. Seleziona le tue foto senza l'API

Seleziona le tue foto prima di caricarle per l'editing. La selezione non fa parte dell'API di Imagen.
 

3. Crea un progetto e ottieni un ID progetto

Ti consigliamo di creare un progetto per ogni servizio fotografico. Un progetto organizza le tue foto con il Profilo AI che hai scelto per l'editing. Ecco la documentazione API di riferimento per questo endpoint.

POST /v1/projects/

Esempio di risposta

La risposta è il project_uuid usato per identificare questo progetto. Usa questo project_uuid finché non esporti le tue foto in JPEG.

{

"data": {

"project_uuid": "<project_uuid>"

}

}
 

4. Crea link temporanei per caricare le foto

Ti serve un link temporaneo per caricare ogni foto. Nella richiesta, nel parametro files_list, includi i nomi dei file delle foto da caricare. Usa il formato list. Ecco i documenti API di riferimento per questo endpoint.

POST /v1/projects/<PROJECT_UUID>/get_temporary_upload_links

Esempio di richiesta

curl --location 'https://api.dev.imagen-ai.com/v1/projects/<project_uuid>/get_temporary_upload_links' \

--header 'x-api-key: <api_key>' \

--header 'Content-Type: application/json' \

--data '{

    “files_list”: [

        {“file_name”: “922A4846.CR2”},

        {“file_name”: “922A4832.CR2”},

        {“file_name”: “922A4818.CR2”},

        {“file_name”: “922A4809.CR2”}

    ]

}'

 

Esempio di risposta

La risposta include un link temporaneo per ogni foto al bucket S3 di Imagen su AWS. Questo link è l'URL prefirmato AWS.

{

"data": {

"files_list": [

{

"file_name": "922A4846.raw",

"upload_link": "<presigned URL for 922A4846.raw>"

},

{

"file_name": "922A4832.raw",

"upload_link": "<presigned URL for 922A4832.raw>"

},

{

"file_name": "922A4818.raw",

"upload_link": "<presigned URL for 922A4818.raw>"

},

{

"file_name": "922A4809.raw",

"upload_link": "<presigned URL for 922A4809.raw>"

}

]

}

}

 

5. Carica ogni foto nel suo link di caricamento temporaneo

Carica le foto con una richiesta PUT al bucket S3 di Imagen su AWS. Usa i link di caricamento temporanei dalla risposta del passaggio precedente.

Test in Postman

  • Disabilita Content-Type negli header.
  • Non inviare Content-Type nei parametri della query.

Requisiti dell'header della richiesta nel codice

Aggiungi Content-Type all'header con una stringa vuota ("") come valore.
 

6. Modifica le foto nel tuo progetto

Prima di inviare le tue foto da modificare, ti serve:

  • Il valore del tuo project_uuid
  • Il valore del tuo profile_key. Vedi la risposta da 1. Ottieni un elenco dei profili AI disponibili per il tuo profile_key.
  • Strumenti AI. Vedi Strumenti AI di Imagen per scegliere gli strumenti giusti per il tuo progetto.
  • (Facoltativo) URL di callback. Vedi [Aggiungi un URL di callback per ricevere messaggi di stato]

Ecco i documenti di riferimento API per questo endpoint.

POST /v1/projects/{project_uuid}/edit

Esempio di richiesta

{

  "profile_key": <chiave profilo>,

  "hdr_merge": true,

  "photography_type": "REAL_ESTATE",

  "callback_url": "string",

  "perspective_correction": true,

"sky_replacement": true,

"sky_replacement_template_id": “2”

}

Esempio di risposta

La risposta è un messaggio che conferma che il progetto è stato modificato con successo. In caso di errore, invia un'email al nostro team di assistenza clienti.

{“project_uuid”: “<UUID del progetto>”, “status”: “Failed/Completed/Pending”, “action”: “edit/export”“}

 

Aggiungi un URL di callback per ricevere messaggi di stato

Il callback_url è un endpoint POST che Imagen può usare per inviarti messaggi di stato. Questo parametro è opzionale. Se lo usi, non devi controllare lo stato dell'edit. Questo endpoint deve essere accessibile a Imagen.

Gli stati possibili inviati nella richiesta sono:

Esempio di risposta

{“project_uuid”: “<UUID del progetto>”, “status”: “Failed/Completed”, “action”: “edit/export”“}

 

7. Controlla lo stato dell'editing

Se non hai aggiunto un URL di callback alla tua richiesta di editing, ottieni lo stato attuale del processo di editing. Continua a chiamare questo endpoint con long polling finché lo stato non è Completato.

Ecco i documenti API di riferimento per questo endpoint.

GET /v1/projects/<PROJECT_UUID>/edit/status

Ecco gli stati nella risposta:

  • In attesa: Il processo di editing non è ancora iniziato. Una volta che l'editing inizia, lo stato cambierà in In corso.
  • In corso: L'API Imagen sta elaborando le foto.
  • Non riuscito: Invia un'email al team di assistenza clienti.
  • Completato: l'API di Imagen ha finito di editare le foto. Continua con una delle seguenti opzioni:

8. Ottieni link temporanei per scaricare le foto editate o gli XMP

Dopo aver ricevuto lo stato Completato, ottieni i link temporanei per scaricare le foto editate.

Ecco la documentazione API di riferimento per questo endpoint.

GET /v1/projects/<PROJECT_UUID>/edit/get_temporary_download_links 

Esempio di risposta

La risposta include un link temporaneo per ogni foto al bucket S3 di Imagen su AWS. Questo link è l'URL prefirmato AWS.

{

"data": {

"files_list": [

{

"file_name": "922A4846.DNG",

"download_link": "<presigned URL for 922A4846.DNG>"

},

{

"file_name": "922A4832.DNG",

"download_link": "<presigned URL for 922A4832.DNG>"

},

{

"file_name": "922A4818.DNG",

"download_link": "<presigned URL for 922A4818.DNG>"

},

{

"file_name": "922A4809.DNG",

"download_link": "<presigned URL for 922A4809.DNG>"

}

]

}

}

 

9. Scarica le foto modificate in locale

Quando Imagen restituisce i file modificati, questi sono i rispettivi formati:

Formato file prima della modifica Formato file restituito dopo la modifica
RAW

XMP

Nota: quando modifichi foto con Unione HDR, il formato restituito è sempre DNG, anche se il formato del file prima della modifica era RAW.
RAW + DNG DNG con XMP incorporato
DNG DNG con XMP incorporato
JPEG JPEG con XMP incorporato


Scarica le foto dal bucket S3 di Imagen su AWS usando i link di download temporanei dalla risposta del passaggio precedente. Usa il metodo che preferisci. Per un esempio di codice in Python, vedi api_client.py nel progetto Imagen API su Github.

Controlla gli edit nel software di editing Adobe. Se apri le foto con il visualizzatore predefinito del tuo computer, non vedrai gli edit. Per aiuto, vedi:

10. Facoltativo: esporta i JPEG finali per la consegna

L'API di Imagen esporta tutte le foto di un progetto in formato JPEG. Questo passaggio è facoltativo. Alcuni fotografi regolano gli edit e li esportano con il loro software di editing. Dopo aver esportato i JPEG finali, li consegni o li carichi in una galleria.

1. Esporta le foto nel progetto

POST /v1/projects/<PROJECT_UUID>/export 

Ecco la documentazione API di riferimento per questo endpoint.

La risposta include il project_uuid e un messaggio che conferma il successo dell'esportazione. In caso di errore, scrivi al nostro team di assistenza.

 

2. Controlla lo stato dell'esportazione

Se non hai aggiunto un URL di callback nella tua richiesta di editing, ottieni lo stato dell'esportazione.

GET /v1/projects/<PROJECT_UUID>/export/status.

Ecco la documentazione API di riferimento per questo endpoint.

La risposta include lo stato dell'esportazione. Gli stati possibili sono:

  • In corso: l'API di Imagen sta elaborando le foto.
  • Non riuscito: scrivi al team di assistenza.
  • Completato: l'API di Imagen ha terminato l'esportazione delle foto in JPEG.

3. Ottieni i link temporanei per scaricare le foto JPEG finali

Ottieni i link temporanei quando lo stato dell'esportazione risulta COMPLETED.

GET /v1/projects/<PROJECT_UUID>/export/get_temporary_download_links 

Nella richiesta, includi le foto esportate da scaricare nel parametro files_list. Usa il formato list.

Ecco la documentazione API di riferimento per questo endpoint.

Esempio di risposta

La risposta include un link temporaneo per ogni foto al bucket S3 di Imagen su AWS. Questo link è l'URL prefirmato AWS.

{

"data": {

"files_list": [

{

"file_name": "922A4846.JPG",

"download_link": "<URL prefirmato per 922A4846.JPG>"

},

{

"file_name": "922A4832.JPG",

"download_link": "<presigned URL for 922A4832.JPG>"

},

{

"file_name": "922A4818.JPG",

"download_link": "<presigned URL for 922A4818.JPG>"

},

{

"file_name": "922A4809.JPG",

"download_link": "<presigned URL for 922A4809.JPG>"

}

]

}

}

 

4. Scarica le foto JPEG finali in locale

Scarica le foto dal bucket S3 di Imagen su AWS usando i link temporanei dalla risposta del passaggio precedente. Usa il metodo che preferisci. Per un esempio di codice in Python, vedi api_client.py nel progetto API di Imagen su Github.

Questo articolo ti è stato utile?

Altre domande? Invia una richiesta