API di Immagine in immagine

Modifica e trasforma immagini nella tua applicazione. Invia immagini di riferimento e un prompt testuale, e i modelli di IA di Meshy generano una nuova immagine a partire da essi.

Immagine in immagine crea immagini. Per creare un modello 3D di ciò che è presente in un'immagine, utilizza Immagine in 3D. Per creare un oggetto che puoi tenere in mano o stampare a partire da una foto, utilizza le API di Creative Lab. Esse creano un'immagine prototipo e poi costruiscono un modello 3D a partire da essa, ad esempio un portachiavi, un magnete da frigo, una statuina, una lampada o un keycap.

POST/openapi/v1/image-to-image

Crea un task Immagine in immagine

Crea un task Immagine in immagine. Il task viene eseguito in background. Per informazioni sulla durata tipica di un task, vedi Tempi di elaborazione.

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"
}

Parametri

Name
ai_model
Type
string
Obbligatorio
Description
Il modello AI che genera l'immagine. I prezzi variano in base al modello. Vedi Prezzi.
Valori disponibili:
- nano-banana: il modello standard
- nano-banana-2: più capace di nano-banana
- nano-banana-2-lite: una versione lite di nano-banana-2
- nano-banana-pro: il modello Pro, con qualità superiore. Richiede un piano Pro o superiore. Su un piano inferiore, restituisce 402.
- gpt-image-2: OpenAI GPT Image 2
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
Name
prompt
Type
string
Obbligatorio
Description
Testo che descrive la modifica o la trasformazione da applicare alle immagini di riferimento.

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii reference_image_urls. L'ID di un task Testo in immagine o Immagine in immagine le cui immagini usare come riferimento, inclusi i task multi-vista. Il task deve essere uno che hai creato con l'API e avere lo stato SUCCEEDED.
Meshy utilizza ogni immagine prodotta dal task. Un task a immagine singola fornisce un'immagine di riferimento, mentre un task multi-vista ne fornisce una per ogni vista. Quindi un singolo ID di task può riempire diversi dei cinque slot di riferimento disponibili.
Il task deve rientrare ancora nel periodo di conservazione degli asset. Dopo la scadenza, il suo ID restituisce 404.

Name
reference_image_urls
Type
array
Obbligatorio
Description
Obbligatorio a meno che tu non invii input_task_id. Da una a cinque immagini di riferimento da modificare, ciascuna come URL pubblico o Data URI, ad esempio data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. Un array vuoto, o più di cinque immagini, restituisce 400. Se invii entrambi, Meshy utilizza input_task_id.
Ogni immagine deve essere un file .jpg, .jpeg, .png o .webp di al massimo 20 MB, e di almeno 32 × 32 pixel.

Name
generate_multi_view
Type
boolean
predefinito false
Description
Indica se generare un'immagine multi-vista che mostri il soggetto da diverse angolazioni. Quando è true, non puoi inviare aspect_ratio. Inviare entrambi restituisce 400.
Name
aspect_ratio
Type
string
predefinito 1:1
Description
Il rapporto d'aspetto dell'immagine di output. I valori che puoi inviare dipendono da ai_model.
Valori disponibili:
- 1:1: quadrato
- 16:9: landscape widescreen
- 9:16: portrait widescreen
- 4:3: landscape standard
- 3:4: portrait standard
- 3:2: landscape, solo modelli GPT Image
- 2:3: portrait, solo modelli GPT Image
I modelli GPT Image sono gpt-image-2, gpt-image-2-5-flare e gpt-image-2-5-sunburst. Con un modello nano-banana, 3:2 e 2:3 restituiscono 400.
Name
remove_background
Type
boolean
predefinito false
Description
Indica se rimuovere lo sfondo. Quando è true, Meshy restituisce l'immagine di output come PNG RGBA trasparente, così puoi posizionare il soggetto su qualsiasi sfondo.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task Immagine in immagine.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: manca un parametro obbligatorio, come ai_model o prompt, oppure non è stato inviato né reference_image_urls né input_task_id.
- Task di input non valido: input_task_id non punta a un task utilizzabile. Deve essere un task Testo in immagine o Immagine in immagine SUCCEEDED, multi-vista incluso, che abbia ancora un output immagine. Meshy rifiuta un task di un altro tipo, un task non riuscito e un task le cui immagini sono tutte scadute.
- Formato immagine non valido: una o più immagini di riferimento non sono in un formato supportato.
- URL non raggiungibile: Meshy non riesce a scaricare una o più immagini reference_image_urls.
- Immagine troppo grande: una o più immagini reference_image_urls superano i 20 MB.
- Immagine troppo piccola: una o più immagini reference_image_urls sono più piccole di 32 × 32 pixel.
- Parametro non valido: aspect_ratio non è uno dei valori supportati dal ai_model selezionato.
- Conflitto: la richiesta invia aspect_ratio insieme a generate_multi_view: true.
Correggi la richiesta, quindi invia di nuovo. Vedi Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
L'account non può eseguire questo task. Ad esempio:
- Piano gratuito: la creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni di abbonamento, quindi riprova.
- Crediti insufficienti: l'account non ha crediti sufficienti per questo task, oppure l'account ha raggiunto un limite di crediti.
- Piano richiesto: la richiesta utilizza nano-banana-pro su un piano inferiore a Pro.
Controlla il saldo dei crediti e il piano, quindi riprova.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessun task nel tuo account. Un task inesistente e un task appartenente a un altro account restituiscono la stessa risposta. Controlla l'ID.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.

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

Ottenere un task Immagine in immagine

Restituisce un task Immagine in immagine tramite il suo ID.

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=***"
  ]
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

L'oggetto task Immagine in immagine.

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

Elimina un task di Immagine in immagine

Elimina definitivamente un task di Immagine in immagine, incluse le sue immagini e i suoi dati. Non è possibile annullare un'eliminazione.

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 keeps 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."
}

Parametri del percorso

Name
id
Type
path
Description
L'ID del task da eliminare.

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task già avviato, quindi eliminarlo comporterebbe la perdita sia dei crediti che del risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Restituisce

200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è IN_PROGRESS.

GET/openapi/v1/image-to-image

Elenco dei task Immagine in immagine

Restituisce un elenco dei tuoi task di Immagine in immagine e Testo in immagine. Il campo type di ciascun task indica a quale dei due appartiene.

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=***"
    ]
  }
]

Parametri

Name
page_num
Type
integer
Description
Il numero di pagina da restituire. Inizia da 1, che è anche il valore predefinito.
Name
page_size
Type
integer
Description
Il numero di task per pagina, fino a 100. Il valore predefinito è 10.
Name
sort_by
Type
string
Description
L'ordine di ordinamento.
Valori disponibili:
- +created_at: dal più vecchio
- -created_at: dal più recente

Restituisce

Un elenco paginato di oggetti task, nello stesso formato dell'oggetto task Immagine in immagine.

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

Esegui lo streaming di un'attività Immagine in immagine

Esegue lo streaming degli aggiornamenti di un'attività Immagine in immagine come Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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=***"
  ]
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività proveniente dalla risposta di creazione.

Valori restituiti

Un flusso di oggetti attività Immagine in immagine come Server-Sent Events.

Ogni evento contiene l'intero oggetto attività, nello stesso formato restituito dall'endpoint Get. Mentre l'attività è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.

L'oggetto task Immagine in immagine

Un oggetto task Immagine in immagine descrive un'immagine generata a partire da immagini di riferimento e un prompt testuale. Contiene lo stato, il progress e le immagini quando il task ha successo.

Proprietà

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
}

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre image-to-image.
Name
ai_model
Type
string
Description
Il modello AI utilizzato dal task.
Valori disponibili:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Il prompt testuale che ha guidato la modifica.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Quanto del task è stato completato, espresso in percentuale. È 0 finché il task non inizia e 100 quando ha successo.
Name
created_at
Type
timestamp
Description
Momento in cui il task è stato creato, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Momento in cui il task è iniziato, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Momento in cui il task è terminato, in millisecondi Unix. È 0 finché il task non termina.
Name
expires_at
Type
timestamp
Description
Momento in cui i risultati del task scadono, in millisecondi Unix.
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo in coda. Il valore è significativo solo mentre il task è PENDING.
Name
image_urls
Type
array
Description
URL di download per le immagini generate. Con generate_multi_view: true, contiene un URL per vista, generalmente tre. Se Meshy non riesce a separare ogni vista, ne restituisce di meno e il task ha comunque successo. Altrimenti, contiene un solo URL.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è PENDING, IN_PROGRESS o SUCCEEDED. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.