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ğı.
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
# 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 modelnano-banana-2:nano-banana'dan daha yeteneklinano-banana-2-lite:nano-banana-2'nin hafif bir sürümünano-banana-2-1: Nano Banana 2.1nano-banana-pro: daha yüksek kalitede Pro model. Pro plan veya üstü gerektirir. Daha düşük bir planda402döndürür.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
- 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ğı.
trueolduğunda,aspect_ratiogönderemezsiniz. İkisini birden göndermek400döndürür.
- Name
- pose_mode
- Type
- string
- Description
Bir karakter için poz,
a-poseveyat-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-litevenano-banana-2-1: Meshy seçtiğiniz modeli korur. Görsel her zaman3:4'tür ve Meshyaspect_ratio'yu yok sayar.nano-bananavenano-banana-pro: Meshy görselinano-banana-proile oluşturur, bu nedenle görevinai_modeldeğerinano-banana-proolarak geri okunur. Bu, Pro plan veya üstünü gerektirir. Görsel her zaman3:4'tür ve Meshyaspect_ratio'yu yok sayar.- GPT Image modelleri (
gpt-image-2,gpt-image-2-5-flare,gpt-image-2-5-sunburst,gpt-image-2-6-flarevegpt-image-2-6-sunburst): Meshy seçtiğiniz modeli veaspect_ratiodeğ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: kare16:9: geniş ekran yatay9:16: geniş ekran dikey4:3: standart yatay3:4: standart dikey3:2: yatay, yalnızca GPT Image modelleri2:3: dikey, yalnızca GPT Image modelleri
nano-bananamodelleri (nano-banana,nano-banana-2,nano-banana-2-lite,nano-banana-2-1venano-banana-pro)3:2ve2:3için400dö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_modelveyapromptgibi gerekli bir parametre eksik. - Geçersiz parametre:
ai_modelveyaaspect_ratioizin verilen değerlerden biri değil. - Çakışma:
aspect_ratio,generate_multi_view: trueile birlikte gönderildi.
İsteği düzeltin, ardından tekrar gönderin. Bkz. Hatalar.
- Eksik parametre:
- Name
401 - Unauthorized- Description
API anahtarı eksik veya geçersiz.
Authorizationbaş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-proveyanano-bananailepose_modekullanıyor (Only Pro and above users can use nano-banana-proveyaOnly 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ı.
Bir Metinden görsele görevi al
ID'sine göre bir Metinden görsele görevini döndürür.
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=***"
]
}
Parametreler
- Name
- id
- Type
- path
- Description
Oluşturma yanıtından alınan görev ID'si.
Dönüş Değerleri
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
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.
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
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ğeri1'dir.
- Name
- page_size
- Type
- integer
- Description
Sayfa başına görev sayısı, en fazla
100. Varsayılan değeri10'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.
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
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-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
Görevi oluşturmak için kullandığınız metin prompt'u.
- Name
- status
- Type
- string
- Description
Görev durumu,
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDveyaCANCELEDdeğ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ğunda100olur.
- 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
PENDINGdurumundayken anlamlıdır. Değer0olduğunda bu alan çıkarılır.
- Name
- image_urls
- Type
- array
- Description
Oluşturulan görseller için indirme URL'leri.
generate_multi_view: trueile, 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
FAILEDolmadıkçanull'dır. Bkz. Hatalar.
- Name
- consumed_credits
- Type
- integer
- Description
Görevin kullandığı kredi sayısı. Durum
PENDING,IN_PROGRESSveyaSUCCEEDEDolduğunda mevcuttur. Bir görevFAILEDolduğunda0'dır, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.