Görselden Görsele API

Görselden Görsele API, Meshy'nin yapay zeka ile görsel düzenleme yeteneklerini kendi uygulamanıza entegre etmenizi sağlayan bir özelliktir. Güçlü yapay zeka modellerimizle referans görseller ve metin komutları kullanarak mevcut görselleri dönüştürün ve düzenleyin.

POST/openapi/v1/image-to-image

Görselden Görsele Görev Oluştur

Bu uç nokta, yeni bir Görselden Görsele görevi oluşturmanıza olanak tanır. Görselden Görsele görev nesnesi ile hangi özelliklerin dahil olduğunu görmek için Görselden 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.

    Mevcut 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ştirilmiş kaliteye sahip Pro model (görsel başına 9 kredi)
    • gpt-image-2: OpenAI GPT Image 2, yüksek doğrulukta görsel düzenleme modeli (görsel başına 12 kredi)
  • Name
    prompt
    Type
    string
    Zorunlu
    Description

    Referans görsellere uygulamak istediğiniz dönüşüm veya düzenlemenin metin açıklaması.

  • Name
    reference_image_urls
    Type
    array
    Zorunlu
    Description

    Görsel düzenleme görevi için kullanılacak 1 ila 5 referans görselden oluşan bir dizi. Şu anda .jpg, .jpeg ve .png formatlarını destekliyoruz.

    Her görseli sağlamak için iki yol vardır:

    • Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL.
    • Data URI: Görselin base64 ile kodlanmış bir Data URI'si. Bir Data URI örneği: data:image/jpeg;base64,<your base64-encoded image data>.
  • 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
    aspect_ratio
    Type
    string
    varsayılan 1:1
    Description

    Çıktı görselinin 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 manzara
    • 9:16: Geniş ekran portre
    • 4:3: Standart manzara (gpt-image-2 tarafından desteklenmez)
    • 3:4: Standart portre (gpt-image-2 tarafından desteklenmez)
    • 3:2: Manzara (sadece gpt-image-2 tarafından desteklenir)
    • 2:3: Portre (sadece gpt-image-2 tarafından desteklenir)
  • Name
    remove_background
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, çıktı görseli 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 Görselden Görsele görevin id değerini 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, reference_image_urls) eksik.
    • Geçersiz görsel formatı: Bir veya daha fazla referans görsel desteklenmeyen formatlarda.
    • Erişilemez URL: Bir veya daha fazla reference_image_urls indirilemedi.
    • Geçersiz parametre: aspect_ratio, seçilen ai_model için 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/image-to-image
# Transform a reference image with a text prompt
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>"
    ]
  }'


 ## Using Data URI example
curl https://api.meshy.ai/openapi/v1/image-to-image \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "reference_image_urls": [
      "data:image/png;base64,${YOUR_BASE64_ENCODED_IMAGE_DATA}"
    ]
  }'

Yanıt

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

Görselden Görsele Görevi Getir

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek Görselden Görsele görevin benzersiz tanımlayıcısı.

Dönen Değerler

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

İstek

GET
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Yanıt

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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/image-to-image/:id

Görselden Görsele Görevi Sil

Bu uç nokta, tüm ilgili görseller ve veriler dahil olmak üzere bir Görselden Görsele görevini kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek Görselden Görsele görevinin ID'si.

Dönen Değerler

Başarı durumunda 200 OK döner.

İstek

DELETE
/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Yanıt

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

Görselden Görsele Görevleri Listele

Bu uç nokta, Görselden 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ıralama yapılacak alan. Mevcut değerler:

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

Dönen Değerler

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

İstek

GET
/openapi/v1/image-to-image
curl https://api.meshy.ai/openapi/v1/image-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Yanıt

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-image",
    "ai_model": "nano-banana",
    "prompt": "Transform this into a cyberpunk style artwork",
    "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/image-to-image/:id/stream

Görselden Görsele Bir Görevi Yayınla

Bu uç nokta, Görselden Görsele bir görev için Sunucu Tarafından Gönderilen Olaylar (SSE) kullanarak gerçek zamanlı güncellemeler yayınlar.

Parametreler

  • Name
    id
    Type
    path
    Description

    Yayınlanacak Görselden Görsele görevin benzersiz tanımlayıcısı.

Dönen Değerler

Sunucu Tarafından Gönderilen Olaylar olarak Görselden 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/image-to-image/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-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": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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=***"
  ]
}

Görselden Görsele Görev Nesnesi

Görselden Görsele Görev nesnesi, Meshy'nin referans görseller ve bir metin prompt girişi ile bir 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 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örsel oluşturma görevinin türü. Görselden Görsele görevler için bu her zaman image-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örsel dönüşümünü yönlendirmek için kullanılan metin prompt.

  • 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, Cuma, 1 Eylül 2023 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şladığı 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 süresinin dolduğu 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örsellere ait indirilebilir URL'lerin bir dizisi. generate_multi_view etkinleştirildiğinde, bu dizi farklı bakış 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).

Örnek Görselden Görsele Görev Nesnesi

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-image",
  "ai_model": "nano-banana",
  "prompt": "Transform this into a cyberpunk style artwork",
  "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
}