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.

POST/openapi/v1/text-to-image

Metinden görsele Görevi Oluşturma

Bu uç nokta, yeni bir Metinden görsele görevi oluşturmanıza olanak tanır. Metinden görsele görev nesnesiyle birlikte hangi özelliklerin yer aldığını görmek için Metinden Görsele Görev Nesnesi bölümüne bakın.

Parametreler

  • Name
    ai_model
    Type
    string
    Zorunlu
    Description

    Görsel oluşturma için kullanılacak modelin ID'si.

    Kullanılabilir değerler:

    • nano-banana: Standart model (görsel başına 3 kredi)
    • nano-banana-2: Standarttan daha güçlü yeteneklere sahip dengeli model (görsel başına 6 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 metin 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, konuyu birden fazla açıdan gösteren bir çoklu görünüm görseli oluşturur.

    generate_multi_view değeri true olduğunda, aspect_ratio parametresi ayarlanamaz.

  • Name
    pose_mode
    Type
    string
    Description

    Karakter oluşturma için poz mode'unu belirtin. Belirtilmediğinde, görsel herhangi bir poz ön ayarı olmadan oluşturulur.

    Kullanılabilir değerler: a-pose, t-pose

  • 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-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 konuyu istediğiniz herhangi bir arka planla birleştirebilirsiniz.

Dönüş Değerleri

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 (örneğin, 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

    Bu görevi gerçekleştirmek için yetersiz kredi.

  • 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örevini Alma

Bu uç nokta, geçerli bir görev id değeri verildiğinde bir Metinden görsele görevini almanıza olanak tanır. Metinden görsele görev nesnesiyle birlikte hangi özelliklerin yer aldığını 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önen Değerler

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 ve buna bağlı tüm görselleri ve verileri 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 kredi iadesi yapılmaz, bu nedenle çalışma sırasında silmek hem kredilerinizi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Sonlanmış bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundayken ise 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

Text to Image Görevlerini Listele

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 değer 10 öğedir. İzin verilen maksimum değer 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ırayla sırala.
    • -created_at: Oluşturulma zamanına göre azalan sırayla sırala.

Dönüş Değerleri

Text to Image Görev Nesnelerinin sayfalanmış bir listesini 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ışla İzleme

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışla izlenecek Metinden görsele görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

Metinden Görsele Görev Nesneleri'nin Server-Sent Events olarak bir akışını 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çerir.

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

The Text to Image Task Object

Text to Image Task nesnesi, text prompt girdisinden bir görsel oluşturmak için Meshy'nin 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 id'leri için k-sıralanabilir bir UUID kullansak da, id'nin formatı hakkında hiçbir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Görsel oluşturma görevinin türü. Text to Image görevleri için bu her zaman text-to-image olacaktır.

  • Name
    ai_model
    Type
    string
    Description

    Bu görev için kullanılan AI modeli. Olası değerler nano-banana, nano-banana-2, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare veya gpt-image-2-5-sunburst'tür.

  • 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 ilerleme durumu. 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 günü GMT 12:00:00 1693569600000 olarak temsil edilir. Bu, Meshy API'deki tüm zaman damgaları için geçerlidir.

  • Name
    started_at
    Type
    timestamp
    Description

    Görevin başladığı 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 bittiği zamanın milisaniye cinsinden zaman damgası. Görev henüz bitmediyse 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'lerin bulunduğu 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ı. Tam task_error nesne 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 krediler iade edilir).

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
}