API Testo in immagine

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

Testo in immagine crea immagini. Per creare un modello 3D di ciò che si trova in un'immagine, usa Immagine in 3D. Per creare un oggetto che puoi tenere in mano o stampare da una foto, usa le API di Creative Lab. Queste 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/text-to-image

Creare un task di Testo in immagine

Crea un task di Testo in immagine. Il task viene eseguito in background. Per sapere quanto tempo richiede di solito un task, 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-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 l'immagine da generare. Una descrizione dettagliata dà risultati migliori.
Name
generate_multi_view
Type
boolean
predefinito false
Description
Indica se generare un'immagine Multi-vista che mostra il soggetto da più 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 e nano-banana-2-lite: Meshy mantiene il modello che hai 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 del task viene restituito come nano-banana-pro. Questo 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 e gpt-image-2-5-sunburst): Meshy mantiene il modello che hai 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 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.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task di 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 manca 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 dell'abbonamento, quindi riprova.
- Crediti insufficienti: l'account non ha crediti sufficienti per questo task (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 saldo dei tuoi crediti e il tuo piano, quindi riprova.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi 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 immagine a partire da un prompt testuale. Contiene lo stato, il progresso e gli URL dell'immagine quando il task ha successo.

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,
  "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 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-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-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
Quanto del task è stato completato, 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 davanti a questo nella coda. Il valore è significativo solo mentre il task è PENDING.
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, solitamente tre. Se Meshy non riesce a separare tutte le viste, 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.