lowpoly 30 Eki 2026 tarihinde kaldırılıyor. 3D oluşturma modeli olarak meshy-7 31 Ara 2026 tarihinde kaldırılıyor; doku modeli olarak kullanılmaya devam ediyor. İstek hatalarını önlemek için bu tarihlerden önce model değiştirin. Tüm kullanımdan kaldırmaları görün

Metinden Görsele API

Meshy'nin yapay zeka modelleriyle bir metin promptundan görseller oluşturun.


POST/openapi/v1/text-to-image

Bir Metinden görsele görevi oluşturun

Bir Metinden görsele görevi oluşturur. Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğünü öğrenmek için bkz. İşlem süreleri.

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

Parametreler

  • Name
    ai_model
    Type
    string
    Zorunlu
    Description

    Görseli oluşturan AI modeli. Fiyatlar modele göre değişir. Fiyatlar için bkz. Fiyatlandırma.

    Kullanılabilir değerler:

    • nano-banana: standart model
    • nano-banana-2: nano-banana'dan daha yetenekli
    • nano-banana-2-lite: nano-banana-2'nin hafif bir sürümü
    • nano-banana-2-1: Nano Banana 2.1
    • nano-banana-pro: daha yüksek kalitede Pro model. Pro plan veya üstü gerektirir. Daha düşük bir planda 402 döndürür.
    • 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
    Zorunlu
    Description

    Oluşturulacak görseli açıklayan metin. Ayrıntılı bir açıklama daha iyi sonuçlar verir.

  • Name
    generate_multi_view
    Type
    boolean
    varsayılan false
    Description

    Konuyu birkaç açıdan gösteren bir çoklu görünüm görseli oluşturulup oluşturulmayacağı. true olduğunda, aspect_ratio gönderemezsiniz. İkisini birden göndermek 400 döndürür.

  • Name
    pose_mode
    Type
    string
    Description

    Bir karakter için poz, a-pose veya t-pose. Poz istemiyorsanız boş bırakın.

    Bir pozun nasıl çalıştığı ai_model'e bağlıdır:

    • nano-banana-2, nano-banana-2-lite ve nano-banana-2-1: Meshy seçtiğiniz modeli korur. Görsel her zaman 3:4'tür ve Meshy aspect_ratio'yu yok sayar.
    • nano-banana ve nano-banana-pro: Meshy görseli nano-banana-pro ile oluşturur, bu nedenle görevin ai_model değeri nano-banana-pro olarak geri okunur. Bu, Pro plan veya üstünü gerektirir. Görsel her zaman 3:4'tür ve Meshy aspect_ratio'yu yok sayar.
    • GPT Image modelleri (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst, gpt-image-2-6-flare ve gpt-image-2-6-sunburst): Meshy seçtiğiniz modeli ve aspect_ratio değerinizi korur.
  • Name
    aspect_ratio
    Type
    string
    varsayılan 1:1
    Description

    Görselin şekli. Gönderebileceğiniz değerler ai_model'e bağlıdır.

    Kullanılabilir değerler:

    • 1:1: kare
    • 16:9: geniş ekran yatay
    • 9:16: geniş ekran dikey
    • 4:3: standart yatay
    • 3:4: standart dikey
    • 3:2: yatay, yalnızca GPT Image modelleri
    • 2:3: dikey, yalnızca GPT Image modelleri

    nano-banana modelleri (nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-2-1 ve nano-banana-pro) 3:2 ve 2:3 için 400 döndürür.

  • Name
    remove_background
    Type
    boolean
    varsayılan false
    Description

    Görselin arka planının kaldırılıp kaldırılmayacağı. true, şeffaf bir RGBA PNG döndürür, böylece konuyu herhangi bir arka plan üzerine yerleştirebilirsiniz.

Dönüş değerleri

Yanıtın result alanı, yeni Metinden görsele görevinin kimliğini (ID) tutar.

Hata durumları

  • Name
    400 - Bad Request
    Description

    İstek çalıştırılamıyor. Hata mesajı hangi sorunu bulduğunu belirtir. Örneğin:

    • Eksik parametre: ai_model veya prompt gibi gerekli bir parametre eksik.
    • Geçersiz parametre: ai_model veya aspect_ratio izin verilen değerlerden biri değil.
    • Çakışma: aspect_ratio, generate_multi_view: true ile birlikte gönderildi.

    İsteği düzeltin, ardından tekrar gönderin. Bkz. Hatalar.

  • Name
    401 - Unauthorized
    Description

    API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.

  • Name
    402 - Payment Required
    Description

    Hesap bu görevi çalıştıramıyor. Örneğin:

    • Ücretsiz plan: Bir görev oluşturmak ücretli bir plan gerektirir. Abonelik ayarlarınızdan planınızı yükseltin, ardından tekrar deneyin.
    • Yetersiz kredi: Hesabın bu görev için yeterli kredisi yok (Insufficient funds) veya hesap bir kredi sınırına ulaştı.
    • Plan gerekli: İstek, Pro'nun altındaki bir planda nano-banana-pro veya nano-banana ile pose_mode kullanıyor (Only Pro and above users can use nano-banana-pro veya Only Pro and above users can use A/T pose feature (requires nano-banana-pro)).

    Kredi bakiyenizi ve planınızı kontrol edin, ardından tekrar deneyin.

  • Name
    429 - Too Many Requests
    Description

    Hız sınırınızı aştınız. Bekleyin, ardından tekrar deneyin. Bkz. Hız sınırları.


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

Bir Metinden görsele görevi al

ID'sine göre bir Metinden görsele görevini döndürür.

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Oluşturma yanıtından alınan görev ID'si.

Dönüş Değerleri

Metinden görsele görev nesnesi.


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

Bir Metinden görsele görevini sil

Bir Metinden görsele görevini, görselleri ve verileri de dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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

Yol parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek görevin kimliği.

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döner ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu nedenle görevi silmek hem kredilerinizi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundayken 409 Conflict döner.


GET/openapi/v1/text-to-image

Metinden Görsele görevlerini listele

Metinden Görsele ve Görselden Görsele görevlerinizin bir listesini döndürür. Her görevin type alanı, ikisinden hangisi olduğunu belirtir.

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

Parametreler

  • Name
    page_num
    Type
    integer
    Description

    Döndürülecek sayfa numarası. 1'den başlar ve varsayılan değeri 1'dir.

  • Name
    page_size
    Type
    integer
    Description

    Sayfa başına görev sayısı, en fazla 100. Varsayılan değeri 10'dur.

  • Name
    sort_by
    Type
    string
    Description

    Sıralama düzeni.

    Kullanılabilir değerler:

    • +created_at: en eskiden en yeniye
    • -created_at: en yeniden en eskiye

Döndürülenler

Metinden Görsele görev nesnesi ile aynı formatta, sayfalanmış bir görev nesneleri listesi.


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

Bir Metinden görsele görevini akışla izleme

Bir Metinden görsele görevinin güncellemelerini Sunucu Tarafından Gönderilen Olaylar (SSE) olarak akışla sunar.

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Metinden görsele görev nesnelerinin Sunucu Tarafından Gönderilen Olaylar olarak bir akışı.

Her olay, Get uç noktasının döndürdüğü ile aynı biçimde, görev nesnesinin tamamını içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.


Text to Image görev nesnesi

Bir Text to Image görev nesnesi, bir metin prompt'undan yapılan tek bir görsel oluşturma işlemini tanımlar. Görev başarılı olduğunda durumu, ilerlemeyi ve görsel URL'lerini tutar.

Özellikler

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

    Görev kimliği. Bunu opak bir dize olarak kabul edin ve biçimine güvenmeyin.

  • Name
    type
    Type
    string
    Description

    Görev türü, her zaman text-to-image.

  • Name
    ai_model
    Type
    string
    Description

    Görevin kullandığı AI modeli.

    Olası değerler:

    • 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

    Görevi oluşturmak için kullandığınız metin prompt'u.

  • Name
    status
    Type
    string
    Description

    Görev durumu, PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biridir.

  • Name
    progress
    Type
    integer
    Description

    Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0, başarılı olduğunda 100 olur.

  • Name
    created_at
    Type
    timestamp
    Description

    Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.

  • Name
    started_at
    Type
    timestamp
    Description

    Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar bulunmaz.

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar bulunmaz.

  • Name
    expires_at
    Type
    timestamp
    Description

    Görevin sonuçlarının süresinin dolduğu zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar bulunmaz.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Kuyrukta bu görevden önce gelen görev sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır. Değer 0 olduğunda bu alan çıkarılır.

  • Name
    image_urls
    Type
    array
    Description

    Oluşturulan görseller için indirme URL'leri. generate_multi_view: true ile, dizi her görünüm için bir URL tutar, genellikle üç tane. Meshy her görünümü ayıramazsa, daha azını döndürür ve görev yine de başarılı olur. Aksi takdirde, tek bir URL tutar.

  • Name
    task_error
    Type
    object
    Description

    Görev başarısız olduğunda hata ayrıntıları. Durum FAILED olmadıkça null'dır. Bkz. Hatalar.

  • Name
    consumed_credits
    Type
    integer
    Description

    Görevin kullandığı kredi sayısı. Durum PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. Bir görev FAILED olduğunda 0'dır, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.