Metinden görsele API

Metinden görsele API, Meshy'nin yapay zeka görsel oluşturma yeteneklerini kendi uygulamanıza entegre etmenizi sağlayan bir özelliktir. Güçlü yapay zeka modellerimizi kullanarak metin istemlerinden yüksek kaliteli görseller oluşturun.

Bu uç nokta görseller üretir. Amacınız elinize alabileceğiniz veya yazdırabileceğiniz bir nesne ise — bir fotoğraftan anahtarlık, buzdolabı mıknatısı, figür, lamba veya keycap gibi — Creative Lab API'lerini kullanın (prototip görsel → 3D model oluşturma). Amacınız resimdeki şeyin 3D modelini elde etmekse, Görselden 3D'ye özelliğini kullanın.

POST/openapi/v1/text-to-image

Metinden Görsele Görevi Oluştur

Bu uç nokta, yeni bir Metinden görsele görevi oluşturmanıza olanak tanır. Metinden görsele görev nesnesinde yer alan özellikleri görmek için Metinden Görsele Görev Nesnesi bölümüne bakın.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü görmek için bkz. İşlem Süreleri.

Parametreler

Name
ai_model
Type
string
Zorunlu
Description
Görsel oluşturma için kullanılacak modelin kimliği.
Kullanılabilir değerler:
- nano-banana: Standart model (görsel başına 3 kredi)
- nano-banana-2: Standart modelden daha güçlü yeteneklere sahip dengeli model (görsel başına 6 kredi)
- nano-banana-2-lite: nano-banana-2'nin hafif varyantı (görsel başına 3 kredi)
- nano-banana-pro: Gelişmiş kaliteye sahip Pro model (görsel başına 9 kredi)
- gpt-image-2: OpenAI GPT Image 2, yüksek sadakatli bir görsel modeli (görsel başına 9 kredi)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), yüksek sadakatli bir görsel modeli (görsel başına 9 kredi)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), yüksek sadakatli bir görsel modeli (görsel başına 9 kredi)
Name
prompt
Type
string
Zorunlu
Description
Oluşturmak istediğiniz görselin metinsel açıklaması. En iyi sonuçlar için açıklayıcı olun.
Name
generate_multi_view
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, öznenin birden fazla açıdan gösterildiği çoklu görünüm bir görsel oluşturur.
generate_multi_view true olduğunda, aspect_ratio parametresi ayarlanamaz.
Name
pose_mode
Type
string
Description
Karakter oluşturma için poz modunu belirtin. Belirtilmediğinde, görsel herhangi bir poz ön ayarı olmadan oluşturulur.
Kullanılabilir değerler: a-pose, t-pose
nano-banana, nano-banana-2, nano-banana-2-lite ve nano-banana-pro ile pose_mode ayarlanması, çıktının en boy oranını 3:4 olarak sabitler ve gönderdiğiniz herhangi bir aspect_ratio göz ardı edilir. nano-banana-2 ve nano-banana-2-lite, istenen modeli korur. nano-banana veya nano-banana-pro ile, pozlanmış görsel nano-banana-pro tarafından oluşturulur (görevin ai_model değeri nano-banana-pro olarak geri okunur) ve bu da Pro plan veya üzerini gerektirir. GPT Image modelleri (gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst) istenen modeli ve aspect_ratio değerini korur.
Name
aspect_ratio
Type
string
varsayılan 1:1
Description
Oluşturulan görselin en boy oranını belirtin. İzin verilen değerler, seçilen ai_model'e bağlıdır:
- nano-banana, nano-banana-2, nano-banana-2-lite, 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
Kullanılabilir değerler:
- 1:1: Kare format
- 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 tarafından desteklenir)
- 2:3: Dikey (yalnızca GPT Image modelleri tarafından desteklenir)
Name
remove_background
Type
boolean
varsayılan false
Description
true olarak ayarlandığında, oluşturulan görsel arka planı kaldırılmış şeffaf bir RGBA PNG olarak döndürülür, böylece özneyi herhangi bir arka planla birleştirebilirsiniz.

Döndürülenler

Yanıtın result özelliği, yeni oluşturulan Metinden görsele görevinin id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: Gerekli bir parametre (ör. ai_model, prompt) eksik.
- Geçersiz parametre: ai_model veya aspect_ratio izin verilen değerlerden biri değil.
- Çakışma: generate_multi_view ve aspect_ratio aynı anda kullanılamaz.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Yaygın nedenler:
- Yetersiz kredi: Hesabınızda bu görevi gerçekleştirmek için yeterli kredi yok (Insufficient funds).
- Plan gerekli: nano-banana-pro, veya nano-banana ile pose_mode kullanımı, Pro plan veya üzerini gerektirir (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)).
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

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

Bir Metinden Görsele Görevi Alma

Bu uç nokta, geçerli bir görev id'si verildiğinde bir Metinden görsele görevini almanızı sağlar. Metinden görsele görev nesnesiyle hangi özelliklerin dahil edildiğini görmek için Metinden Görsele Görev Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak Metinden görsele görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, Metinden görsele görev nesnesini içerir. Ayrıntılar için Metinden Görsele Görev Nesnesi bölümüne bakın.

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

Bir Metinden Görsele Görevini Sil

Bu uç nokta, bir Metinden Görsele görevini, ilişkili tüm görseller ve verilerle birlikte kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

Name
id
Type
path
Description
Silinecek Metinden Görsele görevinin ID'si.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan krediler iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlattığı bir görev için krediler iade edilemez, bu nedenle devam ederken silmek hem kredilere hem de sonuca mal olur. SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son durumda (SUCCEEDED, FAILED veya CANCELED) olan bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundayken 409 Conflict döner.

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

List Text to Image Tasks

Bu uç nokta, Metinden görsele görevlerinin bir listesini almanızı sağlar.

Parametreler

Name
page_num
Type
integer
Description
Sayfalama için sayfa numarası. 1 ile başlar ve varsayılan değeri 1'dir.
Name
page_size
Type
integer
Description
Sayfa boyutu sınırı. Varsayılan 10 öğedir. İzin verilen maksimum 100 öğedir.
Name
sort_by
Type
string
Description
Sıralama için kullanılacak alan. Kullanılabilir değerler:
- +created_at: Oluşturulma zamanına göre artan sırada sırala.
- -created_at: Oluşturulma zamanına göre azalan sırada sırala.

Döndürülenler

The Text to Image Task Objects için sayfalanmış bir liste döndürür.

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

Bir Metinden Görsele Görevini Akışa Alın

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Metinden görsele görevi için gerçek zamanlı güncellemeleri akışa alır.

Parametreler

Name
id
Type
path
Description
Akışa alınacak Metinden görsele görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Metinden Görsele Görev Nesnelerini Server-Sent Events olarak bir akış şeklinde döndürür.

PENDING veya IN_PROGRESS durumundaki görevler için, yanıt akışı yalnızca gerekli progress ve status alanlarını içerecektir.

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

Metinden Görsele Görev Nesnesi

Metinden Görsele Görev nesnesi, Meshy'nin bir metin prompt girdisinden görsel oluşturmak için takip ettiği bir iş birimidir. Nesne aşağıdaki özelliklere sahiptir:

Özellikler

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev kimlikleri için k-sıralanabilir bir UUID kullansak da, kimliğin biçimi hakkında herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Görsel oluşturma görevinin türü. Metinden Görsele görevleri için bu değer her zaman text-to-image olacaktır.
Name
ai_model
Type
string
Description
Bu görev için kullanılan yapay zeka modeli. Olası değerler nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare veya gpt-image-2-5-sunburst'tir.
Name
prompt
Type
string
Description
Görseli oluşturmak için kullanılan metin prompt'u.
Name
status
Type
string
Description
Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biridir.
Name
progress
Type
integer
Description
Görevin ilerlemesi. Görev henüz başlamadıysa, bu özellik 0 olacaktır. Görev başarıyla tamamlandığında bu değer 100 olacaktır.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.
Bir zaman damgası, RFC 3339 standardını takip ederek, 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma 12:00:00 GMT, 1693569600000 olarak temsil edilir. Bu durum Meshy API'deki tüm zaman damgaları için geçerlidir.
Name
started_at
Type
timestamp
Description
Görevin başlatıldığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa, bu özellik 0 olacaktır.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zamanın milisaniye cinsinden zaman damgası. Görev henüz tamamlanmadıysa, bu özellik 0 olacaktır.
Name
expires_at
Type
timestamp
Description
Görev sonucunun süresinin dolacağı zamanın milisaniye cinsinden zaman damgası.
Name
preceding_tasks
Type
integer
Description
Önceki görevlerin sayısı.
Bu alanın değeri yalnızca görev durumu PENDING olduğunda anlamlıdır.
Name
image_urls
Type
array
Description
Oluşturulan görsellere ait indirilebilir URL'lerden oluşan bir dizi. generate_multi_view etkinleştirildiğinde, bu dizi farklı görüntüleme açılarını temsil eden üç görsel URL'si içerir. Aksi takdirde, tek bir görsel URL'si içerir.
Name
task_error
Type
object
Description
Başarısız görevler için hata detayları. task_error nesnesinin tam referansı için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. Görev durumu PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED görevler için 0 döner (başarısızlık durumunda kredi iadesi yapılır).

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
}