Metinden Görsele API

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

POST/openapi/v1/text-to-image

Metinden Görsele Görev Oluştur

Bu uç nokta, yeni bir Metinden Görsele görevi oluşturmanıza olanak tanır. Metinden Görsele görev nesnesiyle hangi özelliklerin dahil olduğunu 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örüntü oluşturma için kullanılacak modelin ID'si.

    Mevcut değerler:

    • nano-banana: Standart model (görüntü başına 3 kredi)
    • nano-banana-2: Standarttan daha güçlü yeteneğe sahip dengeli model (görüntü başına 6 kredi)
    • nano-banana-pro: Geliştirilmiş kaliteye sahip Pro model (görüntü başına 9 kredi)
    • gpt-image-2: OpenAI GPT Image 2, yüksek doğrulukta bir görüntü modeli (görüntü başına 9 kredi)
  • Name
    prompt
    Type
    string
    Zorunlu
    Description

    Oluşturmak istediğiniz görüntünün 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 çoklu görünüm görüntüsü 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örüntü herhangi bir poz ön ayarı olmadan oluşturulur.

    Mevcut değerler: a-pose, t-pose

  • Name
    aspect_ratio
    Type
    string
    varsayılan 1:1
    Description

    Oluşturulan görüntünün 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: 1:1, 16:9, 9:16, 3:2, 2:3

    Mevcut değerler:

    • 1:1: Kare format
    • 16:9: Geniş ekran yatay
    • 9:16: Geniş ekran dikey
    • 4:3: Standart yatay (gpt-image-2 tarafından desteklenmez)
    • 3:4: Standart dikey (gpt-image-2 tarafından desteklenmez)
    • 3:2: Yatay (sadece gpt-image-2 tarafından desteklenir)
    • 2:3: Dikey (sadece gpt-image-2 tarafından desteklenir)
  • Name
    remove_background
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, oluşturulan görüntü arka planı kaldırılmış şeffaf RGBA PNG olarak döndürülür, böylece konuyu herhangi bir arka plana yerleştirebilirsiniz.

Dönüşler

Yanıtın result özelliği, yeni oluşturulan Metinden Görsele görevinin görev id'sini içerir.

Başarısızlık Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemezdi. 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.

İstek

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

Yanıt

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/text-to-image/:id

Metinden Görsele Görevini Getir

Bu uç nokta, geçerli bir görev id verildiğinde bir Metinden Görsele görevini getirmenizi sağlar. Metinden Görsele görev nesnesi ile hangi özelliklerin dahil olduğunu görmek için Metinden Görsele Görev Nesnesi bölümüne bakın.

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek Metinden Görsele görevinin benzersiz tanımlayıcısı.

Dönen Değerler

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

İstek

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

Yanıt

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

Metinden Görsele Görevini Sil

Bu uç nokta, bir Metinden Görsele görevini, ilgili tüm resimler ve veriler dahil olmak üzere 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.

Dönen Değerler

Başarı durumunda 200 OK döner.

İstek

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

Yanıt

// Returns 200 Ok on success.
GET/openapi/v1/text-to-image

Metinden Görsele 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 olarak 1'dir.

  • Name
    page_size
    Type
    integer
    Description

    Sayfa boyutu sınırı. Varsayılan olarak 10 öğedir. İzin verilen maksimum 50 öğedir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralanacak alan. Mevcut değerler:

    • +created_at: Oluşturulma zamanına göre artan sırayla sıralar.
    • -created_at: Oluşturulma zamanına göre azalan sırayla sıralar.

Dönen Değerler

Metinden Görsele Görev Nesneleri listesini sayfalı olarak döndürür.

İstek

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

Yanıt

[
  {
    "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

Metinden Görsele Görevini Yayınla

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Yayınlanacak Metinden Görsele görevinin benzersiz tanımlayıcısı.

Döndürülenler

Server-Sent Events olarak Metinden Görsele Görev Nesneleri akışını döndürür.

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

İstek

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

Yanıt Akışı

// 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 promptu girdisinden bir görüntü 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ı. Görev kimlikleri için k-sıralanabilir UUID kullanıyoruz, ancak id formatı hakkında herhangi bir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Görüntü oluşturma görevinin türü. Metinden Görsele 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 veya gpt-image-2 olabilir.

  • Name
    prompt
    Type
    string
    Description

    Görüntüyü oluşturmak için kullanılan metin promptu.

  • Name
    status
    Type
    string
    Description

    Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED olabilir.

  • 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 100 olacaktır.

  • Name
    created_at
    Type
    timestamp
    Description

    Görevin oluşturulduğu zamanın zaman damgası, milisaniye cinsinden.

    Bir zaman damgası, 1 Ocak 1970 UTC'den itibaren geçen milisaniye sayısını temsil eder ve RFC 3339 standardını takip eder. Örneğin, 1 Eylül 2023 Cuma 12:00:00 PM GMT, 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şlatıldığı zamanın zaman damgası, milisaniye cinsinden. Görev henüz başlamadıysa, bu özellik 0 olacaktır.

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı zamanın zaman damgası, milisaniye cinsinden. Görev henüz tamamlanmadıysa, bu özellik 0 olacaktır.

  • Name
    expires_at
    Type
    timestamp
    Description

    Görev sonucunun sona erdiği zamanın zaman damgası, milisaniye cinsinden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Önceki görevlerin sayısı.

    Bu alanın değeri yalnızca görev durumu PENDING ise anlamlıdır.

  • Name
    image_urls
    Type
    array
    Description

    Oluşturulan görüntülere indirilebilir URL'lerin bir dizisi. generate_multi_view etkinleştirildiğinde, bu dizi farklı görüntüleme açılarını temsil eden üç görüntü URL'si içerir. Aksi takdirde, tek bir görüntü 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).

Örnek Metinden Görsele Görev Nesnesi

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