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.
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
# 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 standardnano-banana-2: più capace dinano-banananano-banana-2-lite: una versione lite dinano-banana-2nano-banana-2-1: Nano Banana 2.1nano-banana-pro: il modello Pro, con qualità superiore. Richiede un piano Pro o superiore. Su un piano inferiore, restituisce402.gpt-image-2: OpenAI GPT Image 2gpt-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 inviareaspect_ratio. Inviare entrambi restituisce400.
- Name
- pose_mode
- Type
- string
- Description
La posa per un personaggio,
a-poseot-pose. Omettilo per nessuna posa.Il funzionamento di una posa dipende da
ai_model:nano-banana-2,nano-banana-2-liteenano-banana-2-1: Meshy mantiene il modello scelto. L'immagine è sempre3:4e Meshy ignoraaspect_ratio.nano-bananaenano-banana-pro: Meshy genera l'immagine connano-banana-pro, quindi l'ai_modeldell'attività viene restituito comenano-banana-pro. Richiede un piano Pro o superiore. L'immagine è sempre3:4e Meshy ignoraaspect_ratio.- I modelli GPT Image (
gpt-image-2,gpt-image-2-5-flare,gpt-image-2-5-sunburst,gpt-image-2-6-flareegpt-image-2-6-sunburst): Meshy mantiene il modello scelto e il tuoaspect_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: quadrato16:9: paesaggio widescreen9:16: ritratto widescreen4:3: paesaggio standard3:4: ritratto standard3:2: paesaggio, solo modelli GPT Image2:3: ritratto, solo modelli GPT Image
I modelli
nano-banana(nano-banana,nano-banana-2,nano-banana-2-lite,nano-banana-2-1enano-banana-pro) restituiscono400per3:2e2:3.
- Name
- remove_background
- Type
- boolean
- predefinito false
- Description
Indica se rimuovere lo sfondo dell'immagine.
truerestituisce 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_modeloprompt. - Parametro non valido:
ai_modeloaspect_rationon è uno dei valori consentiti. - Conflitto:
aspect_ratioè stato inviato insieme agenerate_multi_view: true.
Correggi la richiesta, quindi inviala di nuovo. Consulta Errori.
- Parametro mancante: manca un parametro obbligatorio, come
- 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, oppurepose_modeconnano-banana, su un piano inferiore a Pro (Only Pro and above users can use nano-banana-pro, oppureOnly 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.
Ottieni un task Testo in immagine
Restituisce un task Testo in immagine in base al suo ID.
Request
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
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
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.
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
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.
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
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-banananano-banana-2nano-banana-2-litenano-banana-2-1nano-banana-progpt-image-2gpt-image-2-5-flaregpt-image-2-5-sunburstgpt-image-2-6-flaregpt-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,FAILEDoCANCELED.
- Name
- progress
- Type
- integer
- Description
Quanta parte del task è stata completata, in percentuale. È
0finché il task non inizia e100quando 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. È
nulla meno che lo stato non siaFAILED. Vedi Errori.
- Name
- consumed_credits
- Type
- integer
- Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è
PENDING,IN_PROGRESSoSUCCEEDED. È0per un taskFAILED, perché Meshy rimborsa i crediti quando un task fallisce.