lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

API Testo in immagine

Genera immagini da un prompt di testo con i modelli IA di Meshy.


POST/openapi/v1/text-to-image

Crea un'attività Testo in immagine

Crea un'attività Testo in immagine. L'attività viene eseguita in background. Per sapere quanto tempo richiede di solito un'attività, consulta Tempi di elaborazione.

Request

POST
/openapi/v1/text-to-image
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "aspect_ratio": "16:9"
  }'

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. Per i prezzi, consulta 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-2-1: Nano Banana 2.1
    • 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)
    • gpt-image-2-6-flare: OpenAI GPT Image 2.6 (Flare)
    • gpt-image-2-6-sunburst: OpenAI GPT Image 2.6 (Sunburst)
  • Name
    prompt
    Type
    string
    Obbligatorio
    Description

    Testo che descrive l'immagine da generare. Una descrizione dettagliata offre risultati migliori.

  • Name
    generate_multi_view
    Type
    boolean
    predefinito false
    Description

    Indica se generare un'immagine Multi-vista che mostra il soggetto da diverse angolazioni. Quando è true, non puoi inviare aspect_ratio. Inviare entrambi restituisce 400.

  • Name
    pose_mode
    Type
    string
    Description

    La posa per un personaggio, a-pose o t-pose. Omettilo per nessuna posa.

    Il funzionamento di una posa dipende da ai_model:

    • nano-banana-2, nano-banana-2-lite e nano-banana-2-1: Meshy mantiene il modello scelto. L'immagine è sempre 3:4 e Meshy ignora aspect_ratio.
    • nano-banana e nano-banana-pro: Meshy genera l'immagine con nano-banana-pro, quindi l'ai_model dell'attività viene restituito come nano-banana-pro. Richiede un piano Pro o superiore. L'immagine è sempre 3:4 e Meshy ignora aspect_ratio.
    • I modelli GPT Image (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare e gpt-image-2-6-sunburst): Meshy mantiene il modello scelto e il tuo aspect_ratio.
  • Name
    aspect_ratio
    Type
    string
    predefinito 1:1
    Description

    La forma dell'immagine. I valori che puoi inviare dipendono da ai_model.

    Valori disponibili:

    • 1:1: quadrato
    • 16:9: paesaggio widescreen
    • 9:16: ritratto widescreen
    • 4:3: paesaggio standard
    • 3:4: ritratto standard
    • 3:2: paesaggio, solo modelli GPT Image
    • 2:3: ritratto, solo modelli GPT Image

    I modelli nano-banana (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 e nano-banana-pro) restituiscono 400 per 3:2 e 2:3.

  • Name
    remove_background
    Type
    boolean
    predefinito false
    Description

    Indica se rimuovere lo sfondo dell'immagine. true restituisce un PNG RGBA trasparente, così puoi posizionare il soggetto su qualsiasi sfondo.

Risultati restituiti

Il campo result della risposta contiene l'ID della nuova attività Testo in immagine.

Modalità di errore

  • Name
    400 - Bad Request
    Description

    La richiesta non può essere eseguita. Il messaggio di errore indica quale problema ha riscontrato. Ad esempio:

    • Parametro mancante: manca un parametro obbligatorio, come ai_model o prompt.
    • Parametro non valido: ai_model o aspect_ratio non è uno dei valori consentiti.
    • Conflitto: aspect_ratio è stato inviato insieme a generate_multi_view: true.

    Correggi la richiesta, quindi inviala di nuovo. Consulta 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 questa attività. Ad esempio:

    • Piano gratuito: la creazione di un'attività richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
    • Crediti insufficienti: l'account non dispone di crediti sufficienti per questa attività (Insufficient funds), oppure l'account ha raggiunto un limite di crediti.
    • Piano richiesto: la richiesta usa nano-banana-pro, oppure pose_mode con nano-banana, su un piano inferiore a Pro (Only Pro and above users can use nano-banana-pro, oppure Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).

    Controlla il tuo saldo crediti e il tuo piano, quindi riprova.

  • Name
    429 - Too Many Requests
    Description

    Hai superato il tuo limite di frequenza. Attendi, poi riprova. Consulta Limiti di frequenza.


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

Ottieni un task Testo in immagine

Restituisce un task Testo in immagine in base al suo ID.

Request

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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 Testo in immagine.


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

Elimina un task di Testo in immagine

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

Request

DELETE
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-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 che è già iniziato, quindi eliminarlo ti farebbe perdere sia i crediti che il 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/text-to-image

Elenca attività Testo in immagine

Restituisce un elenco delle tue attività Testo in immagine e Immagine in immagine. Il campo type di ciascuna attività indica a quale delle due appartiene.

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-image",
    "ai_model": "nano-banana",
    "prompt": "A majestic dragon soaring through clouds at sunset",
    "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 e ha come valore predefinito 1.

  • Name
    page_size
    Type
    integer
    Description

    Il numero di attività per pagina, fino a 100. Il valore predefinito è 10.

  • Name
    sort_by
    Type
    string
    Description

    L'ordinamento.

    Valori disponibili:

    • +created_at: dal più vecchio al più recente
    • -created_at: dal più recente al più vecchio

Restituisce

Un elenco paginato di oggetti attività, nello stesso formato dell'oggetto attività Testo in immagine.


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

Esegui lo streaming di un'attività Testo in immagine

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

Request

GET
/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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

Uno stream di oggetti attività Testo in immagine come Server-Sent Events.

Ogni evento contiene l'oggetto attività completo, 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 Testo in immagine

Un oggetto task Testo in immagine descrive una generazione di immagini a partire da un prompt testuale. Contiene lo stato, il progresso e gli URL delle immagini quando il task ha esito positivo.

Proprietà

Example Text to Image Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-image",
  "ai_model": "nano-banana",
  "prompt": "A majestic dragon soaring through clouds at sunset",
  "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=***"
  ],
  "task_error": null,

  "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 text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Il modello AI utilizzato dal task.

    Valori possibili:

    • nano-banana
    • nano-banana-2
    • nano-banana-2-lite
    • nano-banana-2-1
    • nano-banana-pro
    • gpt-image-2
    • gpt-image-2-5-flare
    • gpt-image-2-5-sunburst
    • gpt-image-2-6-flare
    • gpt-image-2-6-sunburst
  • Name
    prompt
    Type
    string
    Description

    Il prompt testuale con cui hai creato il task.

  • Name
    status
    Type
    string
    Description

    Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Quanta parte del task è stata completata, in percentuale. È 0 finché il task non inizia e 100 quando ha esito positivo.

  • Name
    created_at
    Type
    timestamp
    Description

    Ora di creazione del task, in millisecondi Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Ora di avvio del task, in millisecondi Unix. Assente finché il task non inizia.

  • Name
    finished_at
    Type
    timestamp
    Description

    Ora di conclusione del task, in millisecondi Unix. Assente finché il task non termina.

  • Name
    expires_at
    Type
    timestamp
    Description

    Ora in cui scadono i risultati del task, in millisecondi Unix. Assente finché il task non termina.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Il numero di task che precedono questo nella coda. Il valore è significativo solo mentre il task è PENDING. Il campo viene omesso quando il valore è 0.

  • Name
    image_urls
    Type
    array
    Description

    Gli URL di download per le immagini generate. Con generate_multi_view: true, l'array contiene un URL per ogni vista, di solito tre. Se Meshy non riesce a separare tutte le viste, ne restituisce di meno e il task ha comunque esito positivo. Altrimenti, contiene un solo URL.

  • Name
    task_error
    Type
    object
    Description

    I dettagli dell'errore quando il task fallisce. È null a meno che lo stato non sia FAILED. 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.