Görselden Görsele API

Kendi uygulamanızda görselleri düzenleyin ve dönüştürün. Referans görseller ve bir metin prompt'u gönderin, Meshy'nin yapay zeka modelleri bunlardan yeni bir görsel oluştursun.

Görselden görsele, görseller oluşturur. Bir görseldeki içeriğin 3D modelini oluşturmak için Görselden 3D'ye özelliğini kullanın. Bir fotoğraftan elinizde tutabileceğiniz veya yazdırabileceğiniz bir nesne oluşturmak için Creative Lab API'lerini kullanın. Bunlar önce bir prototip görseli oluşturur, ardından ondan bir 3D model inşa eder; örneğin bir anahtarlık, buzdolabı mıknatısı, figür, lamba veya keycap.

POST/openapi/v1/image-to-image

Image to Image görevi oluştur

Bir Image to Image görevi oluşturur. Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü için bkz. İşlem süreleri.

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


 ## Chaining from a previous task, instead of passing image URLs
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",
    "input_task_id": "<your Text to Image or Image to Image task id>"
  }'

Response

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

Parametreler

Name
ai_model
Type
string
Zorunlu
Description
Görseli oluşturan yapay zeka modeli. Fiyatlar modele göre değişir. Bkz. Fiyatlandırma.
Kullanılabilir değerler:
- nano-banana: standart model
- nano-banana-2: nano-banana'dan daha yetenekli
- nano-banana-2-lite: nano-banana-2'nin hafif bir sürümü
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: daha yüksek kaliteli Pro model. Pro plan veya üstü gerektirir. Daha düşük bir planda 402 döndürür.
- gpt-image-2: OpenAI GPT Image 2
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst)
Name
prompt
Type
string
Zorunlu
Description
Referans görsellere uygulanacak düzenleme veya dönüşümü açıklayan metin.

Name
input_task_id
Type
string
Zorunlu
Description
reference_image_urls göndermediğiniz sürece gereklidir. Referans olarak kullanılacak görselleri üreten bir Text to Image veya Image to Image görevinin kimliği; çoklu görünüm görevleri de dahil. Görev, API ile oluşturduğunuz ve durumu SUCCEEDED olan bir görev olmalıdır.
Meshy, görevin ürettiği her görseli kullanır. Tek görsel üreten bir görev bir referans görsel sağlar, çoklu görünüm görevi ise her görünüm için bir tane sağlar. Yani tek bir görev kimliği, beş referans yuvasının birden fazlasını doldurabilir.
Görevin hâlâ varlık saklama süresi içinde olması gerekir. Süre dolduktan sonra kimliği 404 döndürür.

Name
reference_image_urls
Type
array
Zorunlu
Description
input_task_id göndermediğiniz sürece gereklidir. Düzenlenecek bir ila beş referans görsel; her biri genel erişime açık bir URL veya bir data URI olmalıdır, örneğin data:image/jpeg;base64,<your base64-encoded image data>. Boş bir dizi veya beşten fazla görsel 400 döndürür. İkisini de gönderirseniz Meshy input_task_id'yi kullanır.
Her görsel en fazla 20 MB boyutunda ve her kenarı en az 32 piksel olan bir .jpg, .jpeg, .png veya .webp dosyası olmalıdır.

Name
generate_multi_view
Type
boolean
varsayılan false
Description
Konuyu birden fazla açıdan gösteren çoklu görünüm bir görsel oluşturulup oluşturulmayacağı. true olduğunda aspect_ratio gönderemezsiniz. İkisini birden göndermek 400 döndürür.
Name
aspect_ratio
Type
string
varsayılan 1:1
Description
Çıktı görselinin en boy oranı. Gönderebileceğiniz değerler ai_model'e bağlıdır.
Kullanılabilir değerler:
- 1:1: kare
- 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
- 2:3: dikey, yalnızca GPT Image modelleri
GPT Image modelleri gpt-image-2, gpt-image-2-5-flare ve gpt-image-2-5-sunburst'tür. Bir nano-banana modeliyle 3:2 ve 2:3 değerleri 400 döndürür.
Name
remove_background
Type
boolean
varsayılan false
Description
Arka planın kaldırılıp kaldırılmayacağı. true olduğunda Meshy, çıktı görselini saydam bir RGBA PNG olarak döndürür, böylece konuyu herhangi bir arka plana yerleştirebilirsiniz.

Dönüş değerleri

Yanıtın result alanı, yeni Image to Image görevinin kimliğini tutar.

Hata durumları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunu bulduğunu belirtir. Örneğin:
- Eksik parametre: ai_model veya prompt gibi gerekli bir parametre eksik ya da ne reference_image_urls ne de input_task_id gönderilmiş.
- Geçersiz giriş görevi: input_task_id, kullanılabilir bir göreve işaret etmiyor. Çoklu görünüm dahil, hâlâ görsel çıktısı olan, SUCCEEDED durumundaki bir Text to Image veya Image to Image görevi olmalıdır. Meshy, başka bir türdeki bir görevi, başarılı olmamış bir görevi ve görselleri tamamen süresi dolmuş bir görevi reddeder.
- Geçersiz görsel biçimi: Bir veya daha fazla referans görsel desteklenen bir biçimde değil.
- Erişilemeyen URL: Meshy, bir veya daha fazla reference_image_urls görselini indiremiyor.
- Görsel çok büyük: Bir veya daha fazla reference_image_urls görseli 20 MB'den büyük.
- Görsel çok küçük: Bir veya daha fazla reference_image_urls görselinin bir kenarı 32 pikselden kısa.
- Geçersiz parametre: aspect_ratio, seçilen ai_model'in desteklediği değerlerden biri değil.
- Çakışma: İstek, aspect_ratio'yu generate_multi_view: true ile birlikte gönderiyor.
İsteği düzeltip tekrar gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Hesap bu görevi çalıştıramıyor. Örneğin:
- Ücretsiz plan: Bir görev oluşturmak ücretli bir plan gerektirir. Abonelik ayarlarınızdan planınızı yükseltip tekrar deneyin.
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı.
- Plan gerekli: İstek, Pro altındaki bir planda nano-banana-pro kullanıyor.
Kredi bakiyenizi ve planınızı kontrol edip tekrar deneyin.
Name
404 - Not Found
Description
input_task_id, hesabınızdaki bir göreve karşılık gelmiyor. Var olmayan bir görev ile başka bir hesaba ait bir görev aynı yanıtı döndürür. Kimliği kontrol edin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyip tekrar deneyin. Bkz. Hız sınırları.

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

Image to Image görevi alma

Kimliğine göre bir Image to Image görevini döndürür.

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

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Döndürülenler

Image to Image görev nesnesi.

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

Bir Görselden görsele görevini sil

Bir Görselden görsele görevini, görselleri ve verileri dahil olmak üzere kalıcı olarak siler. Silme işlemini geri alamazsınız.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps 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."
}

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin ID'si.

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döndürür ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu nedenle bu görevi silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Son durumda (SUCCEEDED, FAILED veya CANCELED) olan bir görevi silmek, kredilerini iade etmez.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundayken 409 Conflict döner.

GET/openapi/v1/image-to-image

Image to Image görevlerini listele

Image to Image ve Text to Image görevlerinizin bir listesini döndürür. Her görevin type alanı, bu iki türden hangisi olduğunu belirtir.

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

Parametreler

Name
page_num
Type
integer
Description
Döndürülecek sayfa numarası. 1'den başlar ve varsayılan değeri 1'dir.
Name
page_size
Type
integer
Description
Sayfa başına görev sayısı, en fazla 100. Varsayılan değeri 10'dur.
Name
sort_by
Type
string
Description
Sıralama düzeni.
Kullanılabilir değerler:
- +created_at: en eskiden en yeniye
- -created_at: en yeniden en eskiye

Döndürülen Değerler

Image to Image görev nesnesi ile aynı formatta, sayfalanmış bir görev nesneleri listesi.

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

Bir Image to Image görevini akışla izleme

Bir Image to Image görevinin güncellemelerini Server-Sent Events (SSE) olarak akışla sunar.

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.
// These examples are shortened. Each event holds the full task object.
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=***"
  ]
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Server-Sent Events olarak bir Image to Image görev nesneleri akışı.

Her olay, Get uç noktasının döndürdüğüyle aynı biçimde, görev nesnesinin tamamını içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.

Görselden görsele görev nesnesi

Bir Görselden görsele görev nesnesi, referans görsellerden ve bir metin prompt'undan üretilen bir görseli tanımlar. Görev başarılı olduğunda durumu, progress'i ve görselleri tutar.

Özellikler

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,
  "image_urls": [
    "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/image.png?Expires=***"
  ],
  "task_error": null,

  "consumed_credits": 3
}

Name
id
Type
string
Description
Görev kimliği. Bunu opak bir dize olarak kabul edin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman image-to-image.
Name
ai_model
Type
string
Description
Görevin kullandığı AI modeli.
Kullanılabilir değerler:
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-2-1
- nano-banana-pro
- gpt-image-2
- gpt-image-2-5-flare
- gpt-image-2-5-sunburst
Name
prompt
Type
string
Description
Düzenlemeyi yönlendiren metin prompt'u.
Name
status
Type
string
Description
Görev durumu; PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biridir.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0, başarılı olduğunda 100 değerindedir.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar bulunmaz.
Name
finished_at
Type
timestamp
Description
Görevin bittiği zaman, Unix milisaniye cinsinden. Görev bitene kadar bulunmaz.
Name
expires_at
Type
timestamp
Description
Görevin sonuçlarının süresinin dolacağı zaman, Unix milisaniye cinsinden. Görev bitene kadar bulunmaz.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce gelen görev sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır. Değer 0 olduğunda bu alan dahil edilmez.
Name
image_urls
Type
array
Description
Üretilen görseller için indirme URL'leri. generate_multi_view: true ile, genellikle üç olmak üzere görünüm başına bir URL tutar. Meshy her görünümü ayıramazsa daha az döndürür ve görev yine de başarılı olur. Aksi takdirde tek bir URL tutar.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Durum FAILED olmadıkça null değerindedir. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı. Durum PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED bir görev için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.