Görselden görsele API

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

POST/openapi/v1/image-to-image

Görselden görsele Görevi 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 nesnesine hangi özelliklerin dahil edildiğini 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.
Kullanılabilir değerler:
- nano-banana: Standart model (görsel başına 3 kredi)
- nano-banana-2: Standarttan daha güçlü yeteneğe 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ğruluklu bir 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ün 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 biçimlerini destekliyoruz.
Her görseli sağlamanın iki yolu vardır:
- Herkese açık erişilebilir URL: Herkese açık internetten erişilebilen bir URL.
- Data URI: Görselin base64 ile kodlanmış 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, özneyi birden fazla açıdan gösteren çoklu görünüm görseli oluşturur.

Döndürür

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

Hata Durumları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- Eksik parametre: Gerekli bir parametre (örn. ai_model, prompt, reference_image_urls) eksik.
- Geçersiz görsel biçimi: Bir veya daha fazla referans görsel desteklenen biçimlerde değil.
- Erişilemeyen URL: Bir veya daha fazla reference_image_urls indirilemedi.
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/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}"
    ]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-image/:id

Görselden görsele Görevini Al

Bu uç nokta, geçerli bir görev id değeriyle bir Görselden görsele görevini almanızı sağlar. Görselden görsele görev nesnesinde hangi özelliklerin bulunduğunu görmek için Görselden görsele Görev Nesnesi bölümüne bakın.

Parametreler

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

Döndürür

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

Request

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

Response

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

Bir Görselden görsele Görevini Sil

Bu uç nokta, ilişkili tüm 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 kimliği.

Dönüş

Başarılı olduğunda 200 OK döndürür.

Request

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Görselden görsele Görevlerini 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 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ıralama yapılacak alan. Kullanılabilir değerler:
- +created_at: Oluşturulma zamanına göre artan sırada sıralar.
- -created_at: Oluşturulma zamanına göre azalan sırada sıralar.

Döndürür

Görselden görsele Görev Nesneleri için sayfalanmış bir liste döndürür.

Request

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

Response

[
  {
    "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 Görevini Akış Olarak Yayınlama

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

Parametreler

Name
id
Type
path
Description
Akış olarak yayınlanacak Görselden görsele görevi için benzersiz tanımlayıcı.

Dönenler

Server-Sent Events 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çerir.

Request

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

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": "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örsellerden ve bir metin prompt girdisinden 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ı. Uygulama detayı olarak görev id'leri için k-sıralanabilir bir UUID kullansak da, id 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ü. Görselden görsele görevleri 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 şeklindedir.
Name
prompt
Type
string
Description
Görsel dönüşümünü yönlendirmek 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şlamadı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ın milisaniye cinsinden zaman damgası.
Bir zaman damgası, RFC 3339 standardına uygun olarak 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, 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 dolduğu 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 ise anlamlıdır.
Name
image_urls
Type
array
Description
Oluşturulan görsellere ait indirilebilir URL'ler dizisi. generate_multi_view etkinleştirildiğinde, bu dizi farklı görüş 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 mevcuttur. FAILED görevler için 0 döndürür (başarısızlık durumunda kredi iade edilir).

Example Image to Image Task Object

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