Metinden Görsele API

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

Metinden görsele, görseller oluşturur. Bir görseldeki şeyin 3D modelini oluşturmak için Görselden 3D'ye kullanın. Bir fotoğraftan elinizde tutabileceğiniz veya yazdırabileceğiniz bir nesne oluşturmak için Creative Lab API'lerini kullanın. Bunlar önce bir prototip görsel oluşturur, ardından ondan bir 3D model inşa eder; örneğin bir anahtarlık, buzdolabı mıknatısı, figür, lamba veya tuş kapağı.

POST/openapi/v1/text-to-image

Bir Metinden görsele görevi oluşturma

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

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 kaliteli 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)
Name
prompt
Type
string
Zorunlu
Description
Oluşturulacak görseli tanımlayan metin. Ayrıntılı bir açıklama daha iyi sonuçlar verir.
Name
generate_multi_view
Type
boolean
varsayılan false
Description
Konuyu birden fazla açıdan gösteren bir çoklu görünüm görseli oluşturulup oluşturulmayacağı. true olduğunda aspect_ratio gönderemezsiniz. İkisini birlikte 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 olur ve Meshy aspect_ratio'yu dikkate almaz.
- nano-banana ve nano-banana-pro: Meshy görseli nano-banana-pro ile oluşturur, bu nedenle görevin ai_model değeri geri okunduğunda nano-banana-pro olarak görünür. Bunun için Pro plan veya üstü gerekir. Görsel her zaman 3:4 olur ve Meshy aspect_ratio'yu dikkate almaz.
- GPT Image modelleri (gpt-image-2, gpt-image-2-5-flare ve gpt-image-2-5-sunburst): Meshy seçtiğiniz modeli ve aspect_ratio'nuzu 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 plana yerleştirebilirsiniz.

Döndürülenler

Yanıtın result alanı, yeni Metinden görsele görevinin kimliğini 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 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: Görev oluşturmak ücretli bir plan gerektirir. Abonelik ayarlarınızdan planınızı yükseltin, ardından tekrar deneyin.
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok (Insufficient funds) veya hesap bir kredi sınırına ulaştı.
- Plan gerekli: İstek, Pro altında 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, progress'i 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 ID'si. 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
Name
prompt
Type
string
Description
Görevi oluştururken kullandığınız metin prompt'u.
Name
status
Type
string
Description
Görev durumu; PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biri.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0'dır ve 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 dolacağı zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar bulunmaz.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce bulunan görevlerin sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır. Değer 0 olduğunda bu alan atlanı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 sayıda 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ığı sürece 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. FAILED bir görev için 0'dır, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.