API Immagine in immagine

L'API Immagine in immagine è una funzionalità che ti permette di integrare le capacità di modifica delle immagini basate sull'IA di Meshy nella tua applicazione. Trasforma e modifica immagini esistenti utilizzando immagini di riferimento e prompt testuali con i nostri potenti modelli di IA.

Questo endpoint produce immagini. Se l'obiettivo è un oggetto che puoi tenere in mano o stampare — un portachiavi, un magnete da frigo, una statuina, una lampada o un keycap a partire da una foto — usa le API di Creative Lab (immagine del prototipo → crea il modello 3D). Se l'obiettivo è un modello 3D di ciò che è presente nell'immagine, usa Immagine in 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Questo endpoint ti consente di creare un nuovo task Immagine in immagine. Consulta The Image to Image Task Object per vedere quali proprietà sono incluse nell'oggetto task Immagine in immagine.

Il task viene eseguito in background. Per sapere quanto tempo richiede di solito, consulta Processing Times.

Parametri

Name
ai_model
Type
string
Obbligatorio
Description
ID del modello da utilizzare per la generazione dell'immagine.
Valori disponibili:
- nano-banana: modello standard (3 crediti per immagine)
- nano-banana-2: modello bilanciato con capacità superiore rispetto allo standard (6 crediti per immagine)
- nano-banana-2-lite: variante lite di nano-banana-2 (3 crediti per immagine)
- nano-banana-pro: modello Pro con qualità migliorata (9 crediti per immagine)
- gpt-image-2: OpenAI GPT Image 2, un modello di modifica immagine ad alta fedeltà (12 crediti per immagine)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), un modello di modifica immagine ad alta fedeltà (12 crediti per immagine)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), un modello di modifica immagine ad alta fedeltà (12 crediti per immagine)
Name
prompt
Type
string
Obbligatorio
Description
Una descrizione testuale della trasformazione o modifica che desideri applicare alle immagini di riferimento.

Solo uno tra input_task_id o reference_image_urls è obbligatorio. Se entrambi vengono forniti, input_task_id ha la priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID di un task di generazione immagini completato le cui immagini di output devono essere utilizzate come immagini di riferimento. Questo task deve essere uno dei seguenti: Testo in immagine o Immagine in immagine, incluse le relative varianti multi-vista. Inoltre, deve essere stato eseguito tramite l'API e avere uno stato SUCCEEDED.
Vengono utilizzate tutte le immagini di output del task sorgente. Un task a immagine singola fornisce 1 immagine di riferimento; un task multi-vista ne fornisce una per ogni vista generata, quindi un singolo ID di task può riempire diversi degli 5 slot di riferimento disponibili.
Il task sorgente deve trovarsi ancora entro il periodo di conservazione degli asset — una volta scaduto, il suo ID restituisce 404.

Name
reference_image_urls
Type
array
Obbligatorio
Description
Un array da 1 a 5 immagini di riferimento da utilizzare per il task di modifica immagine. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Dimensione massima del file: 20 MB per immagine.
Ci sono due modi per fornire ciascuna immagine:
- URL accessibile pubblicamente: un URL accessibile dalla rete internet pubblica.
- Data URI: un Data URI dell'immagine codificato in base64. Esempio di Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
generate_multi_view
Type
boolean
predefinito false
Description
Se impostato su true, genera un'immagine multi-vista che mostra il soggetto da più angolazioni.
Quando generate_multi_view è true, il parametro aspect_ratio non può essere impostato.
Name
aspect_ratio
Type
string
predefinito 1:1
Description
Specifica il rapporto d'aspetto dell'immagine di output. I valori consentiti dipendono dall'ai_model selezionato:
- nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
Valori disponibili:
- 1:1: formato quadrato
- 16:9: panoramico orizzontale
- 9:16: panoramico verticale
- 4:3: orizzontale standard
- 3:4: verticale standard
- 3:2: orizzontale (supportato solo dai modelli GPT Image)
- 2:3: verticale (supportato solo dai modelli GPT Image)
Name
remove_background
Type
boolean
predefinito false
Description
Se impostato su true, l'immagine di output viene restituita come PNG RGBA trasparente con lo sfondo rimosso, così da poter comporre il soggetto su qualsiasi sfondo.

Valori restituiti

La proprietà result della risposta contiene l'id del task del nuovo task Immagine in immagine appena creato.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: un parametro obbligatorio (ad es. ai_model, prompt) è mancante, oppure non è stato fornito né reference_image_urls né input_task_id.
- Task di input non valido: input_task_id deve fare riferimento a un task Testo in immagine o Immagine in immagine con stato SUCCEEDED (multi-vista incluso) che abbia ancora un output immagine. Un task di qualsiasi altro tipo, uno non andato a buon fine, o uno le cui immagini sono tutte scadute viene rifiutato.
- Formato immagine non valido: una o più immagini di riferimento non sono in formati supportati.
- URL irraggiungibile: una o più reference_image_urls non è stato possibile scaricarle.
- Immagine troppo grande: una o più immagini in reference_image_urls superano i 20 MB.
- Parametro non valido: aspect_ratio non è uno dei valori consentiti per l'ai_model selezionato.
- Conflitto: generate_multi_view e aspect_ratio non possono essere utilizzati simultaneamente.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
404 - Not Found
Description
L'input_task_id non fa riferimento a un task di proprietà del tuo account. Un task inesistente e uno appartenente a un altro account restituiscono la stessa risposta.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

Request

POST

/openapi/v1/image-to-image

# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'


 ## Chaining from a previous task, instead of passing image URLs
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-image/:id

Recuperare un'attività di Immagine in immagine

Questo endpoint consente di recuperare un'attività di Immagine in immagine dato un id di attività valido. Fai riferimento a L'oggetto attività Immagine in immagine per vedere quali proprietà sono incluse nell'oggetto attività Immagine in immagine.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di Immagine in immagine da recuperare.

Restituisce

La risposta contiene l'oggetto attività Immagine in immagine. Consulta la sezione L'oggetto attività Immagine in immagine per i dettagli.

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

DELETE/openapi/v1/image-to-image/:id

Delete an Image to Image Task

Questo endpoint elimina definitivamente un task di Immagine in immagine, comprese tutte le immagini e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID del task di Immagine in immagine da eliminare.

Stato del task

Un task ancora in stato PENDING viene eliminato e i crediti consumati al momento della creazione vengono rimborsati.

Un task già IN_PROGRESS non può essere eliminato: la richiesta viene rifiutata con 409 Conflict e il task continua a essere eseguito. I crediti per un task che il worker ha già iniziato a elaborare non sono rimborsabili, quindi eliminarlo a metà esecuzione vi farebbe perdere sia i crediti sia il risultato. Attendete che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminatelo.

Un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) viene eliminato senza rimborso.

Risultati restituiti

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando il task è IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/image-to-image

Elenco delle attività Immagine in immagine

Questo endpoint consente di recuperare un elenco di attività Immagine in immagine.

Parametri

Name
page_num
Type
integer
Description
Numero di pagina per la paginazione. Inizia e ha come valore predefinito 1.
Name
page_size
Type
integer
Description
Limite di elementi per pagina. Il valore predefinito è 10 elementi. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
Description
Campo in base al quale ordinare. Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di The Image to Image Task Objects.

Request

GET

/openapi/v1/image-to-image

curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1692771650657,
    "started_at": 1692771667037,
    "finished_at": 1692771669037,
    "expires_at": 1692771679037,
    "image_urls": [
      "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
    ]
  }
]

GET/openapi/v1/image-to-image/:id/stream

Trasmetti in streaming un'attività di Immagine in immagine

Questo endpoint trasmette in streaming aggiornamenti in tempo reale per un'attività di Immagine in immagine utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di Immagine in immagine da trasmettere in streaming.

Valori restituiti

Restituisce uno stream di oggetti Attività di Immagine in immagine come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi progress e status necessari.

Request

GET

/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ]
}

L'oggetto Image to Image Task

L'oggetto Image to Image Task è un'unità di lavoro che Meshy tiene traccia per generare un'immagine a partire da immagini di riferimento e un prompt testuale di input. L'oggetto ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco del task. Sebbene utilizziamo un UUID k-sortable per gli id dei task come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Il tipo di task di generazione immagine. Per i task Image to Image, sarà sempre image-to-image.
Name
ai_model
Type
string
Description
Il modello AI utilizzato per questo task. I valori possibili sono nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, o gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Il prompt testuale utilizzato per guidare la trasformazione dell'immagine.
Name
status
Type
string
Description
Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Avanzamento del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è riuscito, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando il task è stato creato, in millisecondi.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, seguendo lo standard RFC 3339. Ad esempio, venerdì 1 settembre 2023 12:00:00 PM GMT è rappresentato come 1693569600000. Questo si applica a tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora completato, questa proprietà sarà 0.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del task scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è PENDING.
Name
image_urls
Type
array
Description
Un array di URL scaricabili per le immagini generate. Quando generate_multi_view è abilitato, questo array contiene tre URL di immagini che rappresentano diverse angolazioni di visualizzazione. Altrimenti, contiene un singolo URL di immagine.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti. Consulta Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).

Example Image to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1692771650657,
  "started_at": 1692771667037,
  "finished_at": 1692771669037,
  "expires_at": 1692771679037,
  "preceding_tasks": 0,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3
}