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.

POST/openapi/v1/image-to-image

Görselden Görsele Görevi Oluşturma

Bu uç nokta, yeni bir Görselden görsele görevi oluşturmanı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
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ü yeteneklere sahip dengeli model (görsel başına 6 kredi)
- nano-banana-pro: Gelişmiş kaliteye sahip Pro model (görsel başına 9 kredi)
- gpt-image-2: OpenAI GPT Image 2, yüksek doğrulukta 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 doğrulukta 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 doğrulukta 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 bir açıklaması.

input_task_id veya reference_image_urls alanlarından yalnızca biri zorunludur. 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örev türlerinden biri olmalıdır: Metinden görsele veya Görselden görsele, çoklu görünüm varyantları da dahil. Ayrıca, 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ğlarken, çoklu görünümlü bir görev oluşturulan her görünüm için bir tane sağlar; bu nedenle tek bir görev ID'si 5 referans yuvasının birkaçını doldurabilir.
Kaynak görev, varlık saklama süresi içinde olmalıdır — süresi 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 ila 5 referans görselden oluşan bir dizi. Şu anda .jpg, .jpeg ve .png formatlarını destekliyoruz.
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 bir ç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, 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 yatay
- 9:16: Geniş ekran dikey
- 4:3: Standart yatay
- 3:4: Standart dikey
- 3:2: Yatay (yalnızca GPT Image modelleri tarafından desteklenir)
- 2:3: Dikey (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 durumundaki 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, başarılı olmamış veya görselleri tamamen süresi dolmuş bir görev reddedilir.
- Geçersiz görsel formatı: Bir veya daha fazla referans görsel desteklenmeyen formatlarda.
- Ulaşılamayan 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
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=***"
  ]
}

Görselden Görsele Görev Nesnesi

Görselden Görsele Görev nesnesi, Meshy'nin referans görseller ve bir metin promptu 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 kimlikleri için k-sıralanabilir bir UUID kullansak da, id'nin biçimi 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örevleri için bu her zaman image-to-image olacaktır.
Name
ai_model
Type
string
Description
Bu görev için kullanılan yapay zeka modeli. Olası değerler nano-banana, nano-banana-2, 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 rehberlik etmek için kullanılan metin promptu.
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 ilerlemesi. Görev henüz başlamadıysa, bu özellik 0 olacaktır. Görev başarılı olduğunda, 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ı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 günü 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şladığı 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 olduğunda 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ı 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
}