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ştur

Bu uç nokta, yeni bir Metinden görsele görevi oluşturmanıza olanak tanır. Metinden görsele görev nesnesine 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ö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ü kapasiteye sahip dengeli model (görsel başına 6 kredi)
    • nano-banana-pro: Geliştirilmiş kaliteye sahip Pro model (görsel başına 9 kredi)
    • gpt-image-2: OpenAI GPT Image 2, sınırlı en-boy oranı desteğine sahip yüksek doğrulukta 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 çoklu görünüm görseli oluşturur.

    generate_multi_view true olduğunda, aspect_ratio parametresi ayarlanamaz.

  • Name
    pose_mode
    Type
    string
    Description

    Karakter oluşturma için pose mode'u belirtin. Atlandığında, 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 değerine 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: yalnızca 1:1, 3:2, 2:3

    Kullanılabilir değerler:

    • 1:1: Kare format
    • 16:9: Geniş ekran yatay ( gpt-image-2 tarafından desteklenmez)
    • 9:16: Geniş ekran dikey ( gpt-image-2 tarafından desteklenmez)
    • 4:3: Standart yatay ( gpt-image-2 tarafından desteklenmez)
    • 3:4: Standart dikey ( gpt-image-2 tarafından desteklenmez)
    • 3:2: Yatay (yalnızca gpt-image-2 tarafından desteklenir)
    • 2:3: Dikey (yalnızca gpt-image-2 tarafından desteklenir)

Dönen Değerler

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

Hata Modları

  • Name
    400 - Bad Request
    Description

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

    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ızı sağlar. Metinden görsele görev nesnesinde 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

Metinden görsele Görevini Sil

Bu uç nokta, ilişkili tüm görseller ve veriler dahil olmak üzere bir Metinden görsele görevini 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öndürür.

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

// 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 değeri 1dir.

  • Name
    page_size
    Type
    integer
    Description

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

  • Name
    sort_by
    Type
    string
    Description

    Sıralanacak alan. Kullanılabilir değerler:

    • +created_at: Oluşturma zamanına göre artan sırada sırala.
    • -created_at: Oluşturma zamanına göre azalan sırada sırala.

Döndürür

Metinden görsele Görev Nesneleri 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

Metinden görsele Görevini Akış Olarak Aktar

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Akış olarak aktarılacak Metinden görsele görevi için benzersiz tanımlayıcı.

Dönenler

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

PENDING veya IN_PROGRESS görevleri 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=***"
  ]
}

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ı. Görev id'leri için uygulama ayrıntısı olarak k-sıralanabilir bir UUID kullansak da, id'nin biçimi hakkında hiç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 AI modeli. Olası değerler nano-banana, nano-banana-2, nano-banana-pro veya gpt-image-2 olabilir.

  • 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 progress değeri. Görev henüz başlatılmadıysa bu özellik 0 olacaktır. Görev başarıyla tamamlandığında bu değer 100 olur.

  • Name
    created_at
    Type
    timestamp
    Description

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

    Bir zaman damgası, 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder ve RFC 3339 standardını izler. Ö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 damgası, milisaniye cinsinden. Görev henüz başlatılmadıysa bu özellik 0 olacaktır.

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

    Görev sonucunun süresinin dolduğu 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ö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 ayrıntıları. 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 bulunur. FAILED görevler için 0 döndürür (kredi, başarısızlık durumunda 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
}