API Imej ke Imej

API Imej ke Imej adalah ciri yang membolehkan anda mengintegrasikan keupayaan penyuntingan imej AI Meshy ke dalam aplikasi anda sendiri. Ubah dan edit imej sedia ada menggunakan imej rujukan dan arahan teks dengan model AI kami yang berkuasa.

POST/openapi/v1/image-to-image

Cipta Tugas Imej ke Imej

Endpoint ini membolehkan anda mencipta tugas Imej ke Imej yang baru. Rujuk kepada Objek Tugas Imej ke Imej untuk melihat sifat-sifat yang disertakan dengan objek tugas Imej ke Imej.

Parameter

Name
ai_model
Type
string
Diperlukan
Description
ID model yang digunakan untuk penjanaan imej.
Nilai yang tersedia:
- nano-banana: Model standard (3 kredit setiap imej)
- nano-banana-2: Model seimbang dengan keupayaan lebih kuat daripada standard (6 kredit setiap imej)
- nano-banana-pro: Model pro dengan kualiti yang dipertingkatkan (9 kredit setiap imej)
- gpt-image-2: OpenAI GPT Image 2, model suntingan imej berketepatan tinggi (12 kredit setiap imej)
Name
prompt
Type
string
Diperlukan
Description
Penerangan teks tentang transformasi atau suntingan yang anda ingin terapkan pada imej rujukan.
Name
reference_image_urls
Type
array
Diperlukan
Description
Satu array 1 hingga 5 imej rujukan untuk digunakan bagi tugas penyuntingan imej. Kami kini menyokong format .jpg, .jpeg, dan .png.
Terdapat dua cara untuk menyediakan setiap imej:
- URL boleh diakses secara awam: URL yang boleh diakses dari internet awam.
- Data URI: Data URI yang dikodkan base64 bagi imej. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, menghasilkan imej berbilang pandangan yang menunjukkan subjek dari pelbagai sudut.
Apabila generate_multi_view adalah true, parameter aspect_ratio tidak boleh ditetapkan.
Name
aspect_ratio
Type
string
lalai 1:1
Description
Tentukan nisbah aspek imej keluaran. Nilai yang dibenarkan bergantung pada ai_model yang dipilih:
- 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
Nilai yang tersedia:
- 1:1: Format segi empat sama
- 16:9: Landskap skrin lebar
- 9:16: Potret skrin lebar
- 4:3: Landskap standard (tidak disokong oleh gpt-image-2)
- 3:4: Potret standard (tidak disokong oleh gpt-image-2)
- 3:2: Landskap (hanya disokong oleh gpt-image-2)
- 2:3: Potret (hanya disokong oleh gpt-image-2)
Name
remove_background
Type
boolean
lalai false
Description
Apabila ditetapkan kepada true, imej keluaran dikembalikan sebagai PNG RGBA telus dengan latar belakang dibuang, jadi anda boleh menggabungkan subjek ke mana-mana latar belakang.

Pulangan

Sifat result dalam respons mengandungi id tugas Imej ke Imej yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: Parameter yang diperlukan (contohnya, ai_model, prompt, reference_image_urls) hilang.
- Format imej tidak sah: Satu atau lebih imej rujukan bukan format yang disokong.
- URL tidak dapat dicapai: Satu atau lebih reference_image_urls tidak dapat dimuat turun.
- Parameter tidak sah: aspect_ratio bukan salah satu nilai yang dibenarkan untuk ai_model yang dipilih.
- Konflik: generate_multi_view dan aspect_ratio tidak boleh digunakan serentak.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

Permintaan

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

Respons

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

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

Dapatkan Tugas Imej ke Imej

Endpoint ini membolehkan anda mendapatkan tugas Imej ke Imej dengan memberikan id tugas yang sah. Rujuk kepada Objek Tugas Imej ke Imej untuk melihat sifat-sifat yang disertakan dengan objek tugas Imej ke Imej.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Imej ke Imej yang ingin diperoleh.

Pulangan

Respons mengandungi objek tugas Imej ke Imej. Semak bahagian Objek Tugas Imej ke Imej untuk butiran lanjut.

Permintaan

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

Respons

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

Padam Tugas Imej ke Imej

Endpoint ini memadamkan secara kekal tugas Imej ke Imej, termasuk semua imej dan data yang berkaitan. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas Imej ke Imej untuk dipadamkan.

Pulangan

Mengembalikan 200 OK jika berjaya.

Permintaan

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

Respons

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

Senarai Tugas Imej ke Imej

Endpoint ini membolehkan anda mendapatkan senarai tugas Imej ke Imej.

Parameter

Name
page_num
Type
integer
Description
Nombor halaman untuk penomboran halaman. Bermula dan tetapan lalai pada 1.
Name
page_size
Type
integer
Description
Had saiz halaman. Tetapan lalai adalah 10 item. Maksimum yang dibenarkan adalah 50 item.
Name
sort_by
Type
string
Description
Medan untuk disusun. Nilai yang tersedia:
- +created_at: Susun mengikut masa penciptaan dalam urutan menaik.
- -created_at: Susun mengikut masa penciptaan dalam urutan menurun.

Mengembalikan

Mengembalikan senarai berpenomboran Objek Tugas Imej ke Imej.

Permintaan

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

Respons

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

Strimkan Tugas Imej ke Imej

Endpoint ini menstrim kemas kini masa nyata untuk tugas Imej ke Imej menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal pasti unik untuk tugas Imej ke Imej yang hendak distrim.

Mengembalikan

Mengembalikan strim Objek Tugas Imej ke Imej sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan menyertakan medan progress dan status yang diperlukan.

Permintaan

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

Strim Respons

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

Objek Tugas Imej ke Imej

Objek Tugas Imej ke Imej adalah unit kerja yang Meshy pantau untuk menjana imej daripada imej rujukan dan input prompt teks. Objek ini mempunyai sifat-sifat berikut:

Sifat-sifat

Name
id
Type
string
Description
Pengenal pasti unik untuk tugas ini. Walaupun kami menggunakan UUID yang boleh diisih k untuk id tugas sebagai butiran pelaksanaan, anda tidak seharusnya membuat sebarang andaian tentang format id tersebut.
Name
type
Type
string
Description
Jenis tugas penjanaan imej. Untuk tugas Imej ke Imej, ini akan sentiasa image-to-image.
Name
ai_model
Type
string
Description
Model AI yang digunakan untuk tugas ini. Nilai yang mungkin adalah nano-banana, nano-banana-2, nano-banana-pro, atau gpt-image-2.
Name
prompt
Type
string
Description
Prompt teks yang digunakan untuk membimbing transformasi imej.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin adalah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Kemajuan tugas. Jika tugas belum dimulakan, sifat ini akan menjadi 0. Setelah tugas berjaya, ini akan menjadi 100.
Name
created_at
Type
timestamp
Description
Cap masa apabila tugas dicipta, dalam milisaat.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut standard RFC 3339. Sebagai contoh, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
started_at
Type
timestamp
Description
Cap masa apabila tugas dimulakan, dalam milisaat. Jika tugas belum dimulakan, sifat ini akan menjadi 0.
Name
finished_at
Type
timestamp
Description
Cap masa apabila tugas selesai, dalam milisaat. Jika tugas belum selesai, sifat ini akan menjadi 0.
Name
expires_at
Type
timestamp
Description
Cap masa apabila hasil tugas tamat tempoh, dalam milisaat.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu.
Nilai medan ini hanya bermakna jika status tugas adalah PENDING.
Name
image_urls
Type
array
Description
Satu array URL yang boleh dimuat turun ke imej yang dijana. Apabila generate_multi_view diaktifkan, array ini mengandungi tiga URL imej yang mewakili sudut pandangan yang berbeza. Jika tidak, ia mengandungi satu URL imej.
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal. Lihat Ralat untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. Hadir apabila status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan jika gagal).

Contoh Objek Tugas Imej ke Imej

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