Bild till bild-API

Bild till bild-API är en funktion som låter dig integrera Meshys AI-bildredigeringsfunktioner i din egen applikation. Omvandla och redigera befintliga bilder med hjälp av referensbilder och textprompter med våra kraftfulla AI-modeller.

Denna endpoint producerar bilder. Om målet är ett objekt du kan hålla i handen eller skriva ut — en nyckelring, kylskåpsmagnet, figur, lampa eller keycap från ett foto — använd Creative Lab APIs (prototypbild → bygg 3D-modell). Om målet är en 3D-modell av det som finns på bilden, använd Bild till 3D.

POST/openapi/v1/image-to-image

Create an Image to Image Task

Denna endpoint låter dig skapa en ny Image to Image-uppgift. Se The Image to Image Task Object för att se vilka egenskaper som ingår i Image to Image-uppgiftsobjektet.

Uppgiften körs i bakgrunden. För information om hur lång tid det vanligtvis tar, se Processing Times.

Parametrar

Name
ai_model
Type
string
Obligatorisk
Description
ID för modellen som ska användas för bildgenerering.
Tillgängliga värden:
- nano-banana: Standardmodell (3 credits per bild)
- nano-banana-2: Balanserad modell med starkare kapacitet än standard (6 credits per bild)
- nano-banana-2-lite: Lite-variant av nano-banana-2 (3 credits per bild)
- nano-banana-pro: Pro-modell med förbättrad kvalitet (9 credits per bild)
- gpt-image-2: OpenAI GPT Image 2, en högkvalitativ bildredigeringsmodell (12 credits per bild)
- gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), en högkvalitativ bildredigeringsmodell (12 credits per bild)
- gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), en högkvalitativ bildredigeringsmodell (12 credits per bild)
Name
prompt
Type
string
Obligatorisk
Description
En textbeskrivning av den transformation eller redigering du vill tillämpa på referensbilderna.

Endast en av input_task_id eller reference_image_urls är obligatorisk. Om båda anges har input_task_id prioritet.

Name
input_task_id
Type
string
Obligatorisk
Description
ID:t för en slutförd bildgenereringsuppgift vars utdatabilder ska användas som referensbilder. Denna uppgift måste vara en av följande uppgiftstyper: Text to Image eller Image to Image, inklusive deras flervy-varianter. Dessutom måste den ha körts via API:et och ha statusen SUCCEEDED.
Alla källuppgiftens utdatabilder används. En uppgift med en enda bild bidrar med 1 referensbild; en flervy-uppgift bidrar med en bild per genererad vy, så ett enda uppgifts-ID kan fylla flera av de 5 referensplatserna.
Källuppgiften måste fortfarande vara inom tillgångslagringsperioden — när den löpt ut returnerar dess ID 404.

Name
reference_image_urls
Type
array
Obligatorisk
Description
En array med 1 till 5 referensbilder att använda för bildredigeringsuppgiften. Vi stöder för närvarande formaten .jpg, .jpeg, .png och .webp.
Maximal filstorlek: 20 MB per bild.
Det finns två sätt att tillhandahålla varje bild:
- Offentligt tillgänglig URL: En URL som är tillgänglig från det offentliga internet.
- Data URI: En base64-kodad data-URI för bilden. Exempel på en data-URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
generate_multi_view
Type
boolean
standard false
Description
När detta är satt till true, genereras en flervy-bild som visar motivet från flera vinklar.
När generate_multi_view är true kan parametern aspect_ratio inte anges.
Name
aspect_ratio
Type
string
standard 1:1
Description
Ange bildförhållandet för utdatabilden. Tillåtna värden beror på vald ai_model:
- 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
Tillgängliga värden:
- 1:1: Kvadratiskt format
- 16:9: Brett liggande format
- 9:16: Brett stående format
- 4:3: Standardliggande
- 3:4: Standardstående
- 3:2: Liggande (stöds endast av GPT Image-modellerna)
- 2:3: Stående (stöds endast av GPT Image-modellerna)
Name
remove_background
Type
boolean
standard false
Description
När detta är satt till true returneras utdatabilden som en transparent RGBA PNG med bakgrunden borttagen, så att du kan sammanfoga motivet med valfri bakgrund.

Returnerar

Egenskapen result i svaret innehåller det id för den nyskapade Image to Image-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran var inte godtagbar. Vanliga orsaker:
- Saknad parameter: En obligatorisk parameter (t.ex. ai_model, prompt) saknas, eller varken reference_image_urls eller input_task_id angavs.
- Ogiltig indatauppgift: input_task_id måste referera till en SUCCEEDED Text to Image- eller Image to Image-uppgift (inklusive flervy) som fortfarande har bildutdata. En uppgift av någon annan typ, en som inte lyckats, eller en vars bilder alla har gått ut, avvisas.
- Ogiltigt bildformat: En eller flera referensbilder har format som inte stöds.
- Onåbar URL: En eller flera reference_image_urls kunde inte laddas ner.
- Bilden är för stor: En eller flera bilder i reference_image_urls överstiger 20 MB.
- Ogiltig parameter: aspect_ratio är inte ett av de tillåtna värdena för vald ai_model.
- Konflikt: generate_multi_view och aspect_ratio kan inte användas samtidigt.
Name
401 - Unauthorized
Description
Autentiseringen misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
404 - Not Found
Description
input_task_id refererar inte till en uppgift som ägs av ditt konto. En uppgift som inte finns och en som tillhör ett annat konto returnerar samma svar.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

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

Hämta en Bild till bild-uppgift

Denna endpoint gör det möjligt att hämta en Bild till bild-uppgift givet ett giltigt id för uppgiften. Se Objektet för Bild till bild-uppgift för att se vilka egenskaper som ingår i objektet för Bild till bild-uppgiften.

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Bild till bild-uppgift som ska hämtas.

Returnerar

Svaret innehåller objektet för Bild till bild-uppgiften. Se avsnittet Objektet för Bild till bild-uppgift för detaljer.

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

Ta bort en Bild till bild-uppgift

Denna endpoint tar bort en Bild till bild-uppgift permanent, inklusive alla tillhörande bilder och data. Denna åtgärd kan inte ångras.

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för den Bild till bild-uppgift som ska tas bort.

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: förfrågan avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat är inte återbetalningsbara, så att ta bort den mitt i körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

En uppgift i ett sluttillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returnerar

Returnerar 200 OK vid lyckad borttagning, eller 409 Conflict när uppgiften är IN_PROGRESS.

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

Lista Bild till bild-uppgifter

Denna endpoint gör det möjligt att hämta en lista med Bild till bild-uppgifter.

Parametrar

Name
page_num
Type
integer
Description
Sidnummer för paginering. Börjar på och har standardvärdet 1.
Name
page_size
Type
integer
Description
Gräns för sidstorlek. Standardvärdet är 10 objekt. Maximalt tillåtna värde är 100 objekt.
Name
sort_by
Type
string
Description
Fält att sortera efter. Tillgängliga värden:
- +created_at: Sortera efter skapandetid i stigande ordning.
- -created_at: Sortera efter skapandetid i fallande ordning.

Returnerar

Returnerar en paginerad lista med Bild till bild-uppgiftsobjekt.

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

Streama en Bild till bild-uppgift

Denna endpoint streamar uppdateringar i realtid för en Bild till bild-uppgift med Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Bild till bild-uppgift som ska streamas.

Returer

Returnerar en ström av The Image to Image Task Objects som Server-Sent Events.

För uppgifter med PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla nödvändiga progress- och status-fält.

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

Objektet Image to Image Task

Objektet Image to Image Task är en arbetsenhet som Meshy håller reda på för att generera en bild utifrån referensbilder och en text-prompt-inmatning. Objektet har följande egenskaper:

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id:n som implementationsdetalj bör du inte göra några antaganden om formatet på id:t.
Name
type
Type
string
Description
Typen av bildgenereringsuppgift. För Image to Image-uppgifter är detta alltid image-to-image.
Name
ai_model
Type
string
Description
AI-modellen som används för denna uppgift. Möjliga värden är nano-banana, nano-banana-2, nano-banana-2-lite, nano-banana-pro, gpt-image-2, gpt-image-2-5-flare eller gpt-image-2-5-sunburst.
Name
prompt
Type
string
Description
Text-prompten som användes för att styra bildtransformationen.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Framsteg (progress) för uppgiften. Om uppgiften inte har startats ännu kommer denna egenskap att vara 0. När uppgiften har lyckats blir den 100.
Name
created_at
Type
timestamp
Description
Tidsstämpel för när uppgiften skapades, i millisekunder.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredagen den 1 september 2023 12:00:00 PM GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startats ännu kommer denna egenskap att vara 0.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften inte har slutförts ännu kommer denna egenskap att vara 0.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftens resultat upphör att gälla, i millisekunder.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter.
Värdet i detta fält är endast meningsfullt om uppgiftens status är PENDING.
Name
image_urls
Type
array
Description
En array med nedladdningsbara URL:er till de genererade bilderna. När generate_multi_view är aktiverat innehåller denna array tre bild-URL:er som representerar olika betraktningsvinklar. Annars innehåller den en enda bild-URL.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga referensen för objektet task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns när uppgiftens status är PENDING, IN_PROGRESS eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).

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
}