API Immagine in immagine

L'API Immagine in immagine è una funzionalità che ti consente di integrare le capacità di modifica delle immagini con 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.

POST/openapi/v1/image-to-image

Crea un'attività Immagine in immagine

Questo endpoint ti consente di creare una nuova attività Immagine in immagine. Consulta L'oggetto attività Immagine in immagine per vedere quali proprietà sono incluse nell'oggetto attività Immagine in immagine.

Parametri

Name
ai_model
Type
string
Obbligatorio
Description
ID del modello da usare per la generazione di immagini.
Valori disponibili:
- nano-banana: Modello standard (3 crediti per immagine)
- nano-banana-2: Modello bilanciato con capacità superiori rispetto allo standard (6 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 immagini ad alta fedeltà (12 crediti per immagine)
Name
prompt
Type
string
Obbligatorio
Description
Una descrizione testuale della trasformazione o della modifica che vuoi applicare alle immagini di riferimento.
Name
reference_image_urls
Type
array
Obbligatorio
Description
Un array da 1 a 5 immagini di riferimento da usare per l'attività di modifica dell'immagine. Attualmente supportiamo i formati .jpg, .jpeg e .png.
Esistono due modi per fornire ciascuna immagine:
- URL accessibile pubblicamente: un URL accessibile da Internet pubblico.
- Data URI: un Data URI codificato in base64 dell'immagine. Esempio di Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
predefinito false
Description
Quando impostato su true, genera un'immagine multi-vista che mostra il soggetto da più angolazioni.

Restituisce

La proprietà result della risposta contiene l'id dell'attività Immagine in immagine appena creata.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- parametro mancante: manca un parametro obbligatorio (ad es. ai_model, prompt, reference_image_urls).
- Formato immagine non valido: una o più immagini di riferimento non sono in formati supportati.
- URL non raggiungibile: non è stato possibile scaricare uno o più reference_image_urls.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
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}"
    ]
  }'

Response

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

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

Recuperare un'attività Immagine in immagine

Questo endpoint ti consente di recuperare un'attività Immagine in immagine dato un id di attività valido. Consulta 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à 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

Elimina un'attività Immagine in immagine

Questo endpoint elimina definitivamente un'attività Immagine in immagine, incluse tutte le immagini e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività Immagine in immagine da eliminare.

Restituisce

Restituisce 200 OK in caso di esito positivo.

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

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Elenca attività di Immagine in immagine

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

Parametri

Name
page_num
Type
integer
Description
Numero di pagina per la paginazione. Inizia da 1 ed è il valore predefinito.
Name
page_size
Type
integer
Description
Limite della dimensione della pagina. Il valore predefinito è 10 elementi. Il massimo consentito è 50 elementi.
Name
sort_by
Type
string
Description
Campo in base al quale ordinare. Valori disponibili:
- +created_at: Ordina per ora di creazione in ordine crescente.
- -created_at: Ordina per ora di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di Oggetti attività Immagine in immagine.

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

Esegui lo stream di un'attività Immagine in immagine

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

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività Immagine in immagine di cui eseguire lo stream.

Restituisce

Restituisce uno stream di Oggetti attività Immagine in immagine come Server-Sent Events.

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

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 attività Immagine in immagine

L'oggetto attività Immagine in immagine è un'unità di lavoro che Meshy monitora per generare un'immagine da immagini di riferimento e da un input prompt testuale. L'oggetto ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco per l'attività. Sebbene usiamo un UUID k-sortable per gli ID delle attività come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Il tipo di attività di generazione immagini. Per le attività Immagine in immagine, questo sarà sempre image-to-image.
Name
ai_model
Type
string
Description
Il modello IA utilizzato per questa attività. I valori possibili sono nano-banana, nano-banana-2, nano-banana-pro o gpt-image-2.
Name
prompt
Type
string
Description
Il prompt testuale utilizzato per guidare la trasformazione dell'immagine.
Name
status
Type
string
Description
Stato dell'attività. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando l'attività è stata creata, 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 l'attività è stata avviata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è stata completata, in millisecondi. Se l'attività non è ancora completata, questa proprietà sarà 0.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato dell'attività scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio delle attività precedenti.
Il valore di questo campo è significativo solo se lo stato dell'attività è 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 diversi angoli di visualizzazione. In caso contrario, contiene un singolo URL di immagine.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Consulta Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Presente quando lo stato dell'attività è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).

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
}