API Immagine in immagine

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

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 con l'oggetto attività Immagine in immagine.

Parametri

  • Name
    ai_model
    Type
    string
    Obbligatorio
    Description

    ID del modello da utilizzare per la generazione delle immagini.

    Valori disponibili:

    • nano-banana: Modello standard (3 crediti per immagine)
    • nano-banana-2: Modello bilanciato con capacità superiore 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 dell'immagine ad alta fedeltà (12 crediti per immagine)
  • Name
    prompt
    Type
    string
    Obbligatorio
    Description

    Una descrizione testuale della trasformazione o modifica che vuoi applicare alle immagini di riferimento.

  • Name
    reference_image_urls
    Type
    array
    Obbligatorio
    Description

    Un array di 1 a 5 immagini di riferimento da utilizzare per l'attività di modifica dell'immagine. Attualmente supportiamo i formati .jpg, .jpeg e .png.

    Ci sono due modi per fornire ogni immagine:

    • URL accessibile pubblicamente: Un URL accessibile da internet pubblico.
    • Data URI: Un Data URI codificato in base64 dell'immagine. Esempio di un 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.

    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 dal ai_model selezionato:

    • nano-banana, nano-banana-2, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
    • gpt-image-2: 1:1, 16:9, 9:16, 3:2, 2:3

    Valori disponibili:

    • 1:1: Formato quadrato
    • 16:9: Paesaggio widescreen
    • 9:16: Ritratto widescreen
    • 4:3: Paesaggio standard (non supportato da gpt-image-2)
    • 3:4: Ritratto standard (non supportato da gpt-image-2)
    • 3:2: Paesaggio (supportato solo da gpt-image-2)
    • 2:3: Ritratto (supportato solo da gpt-image-2)
  • Name
    remove_background
    Type
    boolean
    predefinito false
    Description

    Quando impostato su true, l'immagine di output viene restituita come un PNG RGBA trasparente con lo sfondo rimosso, in modo da poter comporre il soggetto su qualsiasi sfondo.

Restituisce

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

Modalità di fallimento

  • Name
    400 - Bad Request
    Description

    La richiesta non è accettabile. Cause comuni:

    • Parametro mancante: Un parametro richiesto (ad es., ai_model, prompt, reference_image_urls) è mancante.
    • Formato immagine non valido: Una o più immagini di riferimento non sono in formati supportati.
    • URL non raggiungibile: Uno o più reference_image_urls non possono essere scaricati.
    • Parametro non valido: aspect_ratio non è uno dei valori consentiti per il ai_model selezionato.
    • Conflitto: generate_multi_view e aspect_ratio non possono essere usati simultaneamente.
  • Name
    401 - Unauthorized
    Description

    Autenticazione fallita. Si prega di controllare 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.

Richiesta

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

Risposta

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-image/:id

Recupera un'attività Immagine in immagine

Questo endpoint ti consente di recuperare un'attività Immagine in immagine dato un id valido dell'attività. Consulta L'oggetto Attività Immagine in immagine per vedere quali proprietà sono incluse con l'oggetto attività Immagine in immagine.

Parametri

  • Name
    id
    Type
    path
    Description

    Identificatore univoco per l'attività Immagine in immagine da recuperare.

Restituisce

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

Richiesta

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

Risposta

{
  "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 permanentemente un'attività Immagine in immagine, comprese 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 successo.

Richiesta

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

Risposta

// Returns 200 Ok on success.
GET/openapi/v1/image-to-image

Elenco delle attività Immagine in immagine

Questo endpoint ti 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 predefinito a 1.

  • Name
    page_size
    Type
    integer
    Description

    Limite di dimensione della pagina. Predefinito a 10 elementi. Il massimo consentito è 50 elementi.

  • Name
    sort_by
    Type
    string
    Description

    Campo per l'ordinamento. Valori disponibili:

    • +created_at: Ordina per tempo di creazione in ordine crescente.
    • -created_at: Ordina per tempo di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di Gli oggetti attività Immagine in immagine.

Richiesta

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

Risposta

[
  {
    "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 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 per l'attività Immagine in immagine da trasmettere.

Restituisce

Restituisce un flusso di Gli oggetti dell'attività Immagine in immagine come Server-Sent Events.

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

Richiesta

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

Flusso di risposta

// 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 tiene traccia per generare un'immagine da immagini di riferimento e un input di prompt di testo. L'oggetto ha le seguenti proprietà:

Proprietà

  • Name
    id
    Type
    string
    Description

    Identificatore univoco per l'attività. Anche se utilizziamo un UUID ordinabile per k per gli id delle attività come dettaglio di implementazione, non dovresti fare alcuna ipotesi sul formato dell'id.

  • Name
    type
    Type
    string
    Description

    Il tipo di attività di generazione dell'immagine. Per le attività Immagine in immagine, questo sarà sempre image-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Il modello AI 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 di testo utilizzato per guidare la trasformazione dell'immagine.

  • Name
    status
    Type
    string
    Description

    Stato dell'attività. I valori possibili sono uno di PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Avanzamento 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à è iniziata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp di quando l'attività è terminata, in millisecondi. Se l'attività non è ancora terminata, 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. Altrimenti, contiene un singolo URL di immagine.

  • Name
    task_error
    Type
    object
    Description

    Dettagli dell'errore per le attività fallite. Vedi 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 fallimento).

Esempio di Oggetto Attività Immagine in immagine

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