Görselden Görsele API

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

Bu uç nokta görseller üretir. Amacınız elinizde tutabileceğiniz veya yazdırabileceğiniz bir nesne ise — bir fotoğraftan anahtarlık, buzdolabı mıknatısı, figür, lamba veya keycap — Creative Lab API'lerini kullanın (prototip görsel → 3D model oluşturma). Amacınız resimdeki şeyin 3D modeli ise, Görselden 3D'ye özelliğini kullanın.

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 nesnesiyle hangi özelliklerin dahil olduğunu görmek için Görselden Görsele Görev Nesnesi bölümüne bakın.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü görmek için İşlem Süreleri sayfasına 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: Standart modelden daha güçlü, dengeli bir model (görsel başına 6 kredi)
- nano-banana-2-lite: nano-banana-2'nin hafif versiyonu (görsel başına 3 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 sadakatli bir görsel düzenleme modeli (görsel başına 12 kredi)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), yüksek sadakatli bir görsel düzenleme modeli (görsel başına 12 kredi)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), yüksek sadakatli 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 veya düzenlemenin metinsel açıklaması.

input_task_id veya reference_image_urls değerlerinden yalnızca biri gereklidir. Her ikisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
Çıktı görsellerinin referans görseller olarak kullanılacağı tamamlanmış bir görsel oluşturma görevinin ID'si. Bu görev şu görevlerden biri olmalıdır: Metinden görsele veya Görselden görsele, bunların çoklu görünüm varyantları da dahil. Ayrıca, bu görev API üzerinden çalıştırılmış olmalı ve durumu SUCCEEDED olmalıdır.
Kaynak görevin tüm çıktı görselleri kullanılır. Tek görselli bir görev 1 referans görsel sağlar; çoklu görünümlü bir görev ise oluşturulan her görünüm için bir tane sağlar, dolayısıyla tek bir görev ID'si 5 referans yuvasından birkaçını doldurabilir.
Kaynak görev hâlâ varlık saklama süresi içinde olmalıdır — süre dolduğunda, ID'si 404 döndürür.

Name
reference_image_urls
Type
array
Zorunlu
Description
Görsel düzenleme görevi için kullanılacak 1 ile 5 arası referans görselden oluşan bir dizi. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.
Maksimum dosya boyutu: görsel başına 20 MB.
Her görseli sağlamanın iki yolu 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. Data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>.

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ümlü bir görsel oluşturur.
generate_multi_view değeri true olduğunda, aspect_ratio parametresi ayarlanamaz.
Name
aspect_ratio
Type
string
varsayılan 1:1
Description
Çıktı görselinin en boy oranını belirtir. İzin verilen değerler seçilen ai_model'e bağlıdır:
- nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro: 1:1, 16:9, 9:16, 4:3, 3:4
- gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
Kullanılabilir değerler:
- 1:1: Kare format
- 16:9: Geniş ekran manzara
- 9:16: Geniş ekran portre
- 4:3: Standart manzara
- 3:4: Standart portre
- 3:2: Manzara (yalnızca GPT Image modelleri tarafından desteklenir)
- 2:3: Portre (yalnızca GPT Image modelleri 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 bir RGBA PNG olarak döndürülür; böylece konuyu herhangi bir arka plana yerleştirebilirsiniz.

Dönüş Değerleri

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

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: Gerekli bir parametre (ör. ai_model, prompt) eksik veya ne reference_image_urls ne de input_task_id sağlanmış.
- Geçersiz giriş görevi: input_task_id, hâlâ görsel çıktısına sahip, SUCCEEDED durumunda bir Metinden görsele veya Görselden görsele görevine (çoklu görünüm dahil) atıfta bulunmalıdır. Başka herhangi bir türdeki bir görev, başarılı olmamış bir görev veya görsellerinin tamamı süresi dolmuş bir görev reddedilir.
- 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.
- Görsel çok büyük: Bir veya daha fazla reference_image_urls görseli 20 MB'yi aşıyor.
- 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
404 - Not Found
Description
input_task_id, hesabınıza ait bir göreve atıfta bulunmuyor. Var olmayan bir görev ile başka bir hesaba ait bir görev aynı yanıtı döndürür.
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}"
    ]
  }'


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

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

Görselden Görsele Görevini Getir

Bu uç nokta, geçerli bir görev id'si verildiğinde bir Görselden görsele görevini almanızı sağlar. Görselden görsele görev nesnesiyle hangi özelliklerin dahil edildiğini 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ülenler

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üne bakın.

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, bir Görselden görsele görevini, ilişkili tüm görselleri ve verileri de dahil olmak üzere 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.

Görev Durumu

Hâlâ PENDING durumundaki bir görev silinir ve oluşturma sırasında harcanan kredi iade edilir.

Zaten IN_PROGRESS durumundaki bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. İşçinin (worker) zaten başlattığı bir görev için krediler iade edilemez, bu nedenle görevi çalışırken silmek hem kredinizi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Sonlanmış bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarı durumunda 200 OK, görev IN_PROGRESS durumundaysa 409 Conflict döner.

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 is left 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."
}

GET/openapi/v1/image-to-image

Image to Image Görevlerini Listele

Bu uç nokta, Image to Image 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 1'dir.
Name
page_size
Type
integer
Description
Sayfa başına öğe sınırı. Varsayılan değer 10 öğedir. İzin verilen maksimum değer 100 öğedir.
Name
sort_by
Type
string
Description
Sıralama için kullanılacak alan. Kullanılabilir değerler:
- +created_at: Oluşturulma zamanına göre artan sırada sırala.
- -created_at: Oluşturulma zamanına göre azalan sırada sırala.

Dönüş Değerleri

Image to Image Görev Nesneleri'nin sayfalanmış bir listesini 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

Bir Görselden Görsele Görevini Akış Olarak İzleme

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

Parametreler

Name
id
Type
path
Description
Akışı izlenecek Görselden görsele görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

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

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

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

The Image to Image Task Object

Image to Image Task nesnesi, Meshy'nin referans görseller ve bir metin prompt girdisinden görsel üretmek 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 kimlikleri için k-sıralanabilir bir UUID kullansak da, kimliğin formatıyla ilgili herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Görsel üretim görevinin türü. Image to Image 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-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare veya gpt-image-2-5-sunburst'tür.
Name
prompt
Type
string
Description
Görsel dönüşümüne yön vermek için kullanılan metin prompt.
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 olacaktır.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.
Bir zaman damgası, RFC 3339 standardını takip ederek 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma, GMT 12:00:00 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 dolacağı 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 olduğunda anlamlıdır.
Name
image_urls
Type
array
Description
Üretilen 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 mevcuttur. FAILED görevler için 0 döner (başarısızlık durumunda krediler 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
}