API Testo in immagine

L'API Testo in immagine è una funzionalità che ti consente di integrare le capacità di generazione di immagini AI di Meshy nella tua applicazione. Genera immagini di alta qualità a partire da prompt testuali utilizzando i nostri potenti modelli AI.

POST/openapi/v1/text-to-image

Creare un'attività di Testo in immagine

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

Parametri

Name
ai_model
Type
string
Obbligatorio
Description
ID del modello da utilizzare per la generazione dell'immagine.
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 immagini ad alta fedeltà (9 crediti per immagine)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), un modello di immagini ad alta fedeltà (9 crediti per immagine)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), un modello di immagini ad alta fedeltà (9 crediti per immagine)
Name
prompt
Type
string
Obbligatorio
Description
Una descrizione testuale dell'immagine che desideri generare. Sii descrittivo per ottenere i migliori risultati.
Name
generate_multi_view
Type
boolean
predefinito false
Description
Se 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
pose_mode
Type
string
Description
Specifica il pose_mode per la generazione del personaggio. Se omesso, l'immagine viene generata senza preset di posa.
Valori disponibili: a-pose, t-pose
Name
aspect_ratio
Type
string
predefinito 1:1
Description
Specifica il rapporto d'aspetto dell'immagine generata. I valori consentiti dipendono dall'ai_model selezionato:
- nano-banana, nano-banana-2, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
Valori disponibili:
- 1:1: formato quadrato
- 16:9: panoramico orizzontale
- 9:16: panoramico verticale
- 4:3: orizzontale standard
- 3:4: verticale standard
- 3:2: orizzontale (supportato solo dai modelli GPT Image)
- 2:3: verticale (supportato solo dai modelli GPT Image)
Name
remove_background
Type
boolean
predefinito false
Description
Se impostato su true, l'immagine generata viene restituita come PNG RGBA trasparente con lo sfondo rimosso, così puoi comporre il soggetto su qualsiasi sfondo.

Valori restituiti

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

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non è stata accettata. Cause comuni:
- Parametro mancante: manca un parametro obbligatorio (es. ai_model, prompt).
- Parametro non valido: ai_model o aspect_ratio non corrisponde a uno dei valori consentiti.
- Conflitto: generate_multi_view e aspect_ratio non possono essere utilizzati contemporaneamente.
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/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"
}

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

Recuperare un Task Testo in immagine

Questo endpoint consente di recuperare un task Testo in immagine specificando un id di task valido. Consulta The Text to Image Task Object per vedere quali proprietà sono incluse nell'oggetto task Testo in immagine.

Parametri

Name
id
Type
path
Description
Identificatore univoco del task Testo in immagine da recuperare.

Restituisce

La risposta contiene l'oggetto task Testo in immagine. Consulta la sezione The Text to Image Task Object per i dettagli.

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=***"
  ]
}

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

Elimina un'attività di Testo in immagine

Questo endpoint elimina definitivamente un'attività di Testo 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à di Testo in immagine da eliminare.

Stato dell'attività

Un'attività ancora in stato PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività che il worker ha già iniziato non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti sia il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

Restituisce

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando l'attività è IN_PROGRESS.

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 is left 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."
}

GET/openapi/v1/text-to-image

Elenca le attività Testo in immagine

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

Parametri

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

Restituisce

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

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=***"
    ]
  }
]

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

Trasmetti in streaming un'attività di Testo in immagine

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

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di Testo in immagine da trasmettere in streaming.

Valori restituiti

Restituisce uno stream di The Text to Image Task Objects come Server-Sent Events.

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

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.
// 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": "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=***"
  ]
}

L'oggetto Task di Testo in immagine

L'oggetto Task di Testo in immagine è un'unità di lavoro che Meshy tiene traccia per generare un'immagine a partire da un input di prompt testuale. L'oggetto ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco per il task. Sebbene utilizziamo un UUID k-sortable per gli id dei task come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Il tipo di task di generazione immagine. Per i task Testo in immagine, sarà sempre text-to-image.
Name
ai_model
Type
string
Description
Il modello AI utilizzato per questo task. I valori possibili sono nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare, oppure gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Il prompt testuale utilizzato per generare l'immagine.
Name
status
Type
string
Description
Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task ha avuto successo, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando il task è stato creato, 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 viene rappresentato come 1693569600000. Questo si applica a tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora avviato, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora completato, questa proprietà sarà 0.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del task scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è 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 diverse angolazioni di visualizzazione. Altrimenti, contiene un singolo URL di immagine.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti. Consulta Errori per il riferimento completo dell'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).

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
}