이미지로 이미지 API

자체 애플리케이션에서 이미지를 편집하고 변환해 보세요. 참조 이미지와 텍스트 prompt를 전송하면 Meshy의 AI 모델이 이를 바탕으로 새로운 이미지를 생성합니다.

이미지로 이미지는 이미지를 생성합니다. 이미지 속 대상의 3D 모델을 만들려면 이미지로 3D를 사용하세요. 사진으로부터 직접 들거나 출력할 수 있는 오브젝트를 만들려면 Creative Lab API를 사용하세요. 이 API는 먼저 프로토타입 이미지를 생성한 다음 이를 바탕으로 3D 모델을 만들며, 예를 들어 키링, 냉장고 자석, 피규어, 램프, 키캡 등을 제작할 수 있습니다.

POST/openapi/v1/image-to-image

이미지로 이미지 작업 생성하기

이미지로 이미지 작업을 생성합니다. 작업은 백그라운드에서 실행됩니다. 작업에 걸리는 일반적인 시간은 처리 시간을 참고하세요.

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

파라미터

Name
ai_model
Type
string
필수
Description
이미지를 생성하는 AI 모델입니다. 모델에 따라 가격이 다릅니다. 요금을 참고하세요.
사용 가능한 값:
- nano-banana: 표준 모델
- nano-banana-2: nano-banana보다 더 뛰어난 모델
- nano-banana-2-lite: nano-banana-2의 경량 버전
- nano-banana-2-1: Nano Banana 2.1
- nano-banana-pro: 더 높은 품질을 제공하는 Pro 모델입니다. Pro 플랜 이상이 필요합니다. 더 낮은 플랜에서는 402를 반환합니다.
- 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
필수
Description
참조 이미지에 적용할 편집 또는 변환 내용을 설명하는 텍스트입니다.

Name
input_task_id
Type
string
필수
Description
reference_image_urls를 보내지 않는 한 필수입니다. 참조로 사용할 이미지가 있는 텍스트로 이미지 또는 이미지로 이미지 작업의 ID로, 멀티뷰 작업도 포함됩니다. 이 작업은 API로 생성한 것이어야 하며 상태가 SUCCEEDED여야 합니다.
Meshy는 해당 작업이 생성한 모든 이미지를 사용합니다. 단일 이미지 작업은 참조 이미지 1개를 제공하고, 멀티뷰 작업은 뷰당 1개씩 제공합니다. 따라서 작업 ID 하나로 다섯 개의 참조 슬롯 중 여러 개를 채울 수 있습니다.
해당 작업은 여전히 에셋 보존 기간 이내여야 합니다. 기간이 만료되면 해당 ID는 404를 반환합니다.

Name
reference_image_urls
Type
array
필수
Description
input_task_id를 보내지 않는 한 필수입니다. 편집할 참조 이미지 1개에서 5개로, 각각 공개 URL 또는 data URI여야 합니다. 예: data:image/jpeg;base64,<your base64-encoded image data>. 빈 배열이거나 이미지가 5개를 초과하면 400을 반환합니다. 둘 다 보내면 Meshy는 input_task_id를 사용합니다.
각 이미지는 최대 20MB 크기의 .jpg, .jpeg, .png, 또는 .webp 파일이어야 하며, 각 변이 최소 32픽셀이어야 합니다.

Name
generate_multi_view
Type
boolean
기본값 false
Description
피사체를 여러 각도에서 보여주는 멀티뷰 이미지를 생성할지 여부입니다. true일 때는 aspect_ratio를 보낼 수 없습니다. 둘 다 보내면 400을 반환합니다.
Name
aspect_ratio
Type
string
기본값 1:1
Description
출력 이미지의 종횡비입니다. 보낼 수 있는 값은 ai_model에 따라 다릅니다.
사용 가능한 값:
- 1:1: 정사각형
- 16:9: 와이드스크린 가로
- 9:16: 와이드스크린 세로
- 4:3: 표준 가로
- 3:4: 표준 세로
- 3:2: 가로, GPT Image 모델 전용
- 2:3: 세로, GPT Image 모델 전용
GPT Image 모델은 gpt-image-2, gpt-image-2-5-flare, gpt-image-2-5-sunburst입니다. nano-banana 모델에서는 3:2와 2:3이 400을 반환합니다.
Name
remove_background
Type
boolean
기본값 false
Description
배경을 제거할지 여부입니다. true일 때 Meshy는 출력 이미지를 투명한 RGBA PNG로 반환하므로, 피사체를 어떤 배경 위에도 배치할 수 있습니다.

반환 값

응답의 result 필드에는 새로 생성된 이미지로 이미지 작업의 ID가 담깁니다.

실패 모드

Name
400 - Bad Request
Description
요청을 실행할 수 없습니다. 오류 메시지에 발견된 문제가 표시됩니다. 예를 들면:
- 파라미터 누락: ai_model 또는 prompt와 같은 필수 파라미터가 누락되었거나, reference_image_urls와 input_task_id 둘 다 보내지 않았습니다.
- 잘못된 입력 작업: input_task_id가 사용 가능한 작업을 가리키지 않습니다. 멀티뷰를 포함하여 이미지 출력이 아직 남아 있는 SUCCEEDED 상태의 텍스트로 이미지 또는 이미지로 이미지 작업이어야 합니다. Meshy는 다른 유형의 작업, 성공하지 않은 작업, 그리고 이미지가 모두 만료된 작업을 거부합니다.
- 잘못된 이미지 형식: 하나 이상의 참조 이미지가 지원되지 않는 형식입니다.
- 접근할 수 없는 URL: Meshy가 하나 이상의 reference_image_urls 이미지를 다운로드할 수 없습니다.
- 이미지가 너무 큼: 하나 이상의 reference_image_urls 이미지가 20MB를 초과합니다.
- 이미지가 너무 작음: 하나 이상의 reference_image_urls 이미지의 한 변이 32픽셀보다 짧습니다.
- 잘못된 파라미터: aspect_ratio가 선택한 ai_model이 지원하는 값 중 하나가 아닙니다.
- 충돌: 요청이 aspect_ratio를 generate_multi_view: true와 함께 보냈습니다.
요청을 수정한 뒤 다시 보내세요. 오류를 참고하세요.
Name
401 - Unauthorized
Description
API 키가 없거나 유효하지 않습니다. Authorization 헤더를 확인하세요.
Name
402 - Payment Required
Description
계정이 이 작업을 실행할 수 없습니다. 예를 들면:
- 무료 플랜: 작업을 생성하려면 유료 플랜이 필요합니다. 구독 설정에서 플랜을 업그레이드한 뒤 다시 시도하세요.
- 크레딧 부족: 계정에 이 작업을 수행할 충분한 크레딧이 없거나, 계정이 크레딧 한도에 도달했습니다.
- 플랜 필요: 요청이 Pro 미만 플랜에서 nano-banana-pro를 사용했습니다.
크레딧 잔액과 플랜을 확인한 뒤 다시 시도하세요.
Name
404 - Not Found
Description
input_task_id가 계정 내 작업과 일치하지 않습니다. 존재하지 않는 작업과 다른 계정에 속한 작업은 동일한 응답을 반환합니다. ID를 확인하세요.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다. 잠시 기다린 뒤 다시 시도하세요. 속도 제한을 참고하세요.

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

이미지로 이미지 작업 가져오기

ID로 이미지로 이미지 작업을 반환합니다.

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

매개변수

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

이미지로 이미지 작업 객체를 반환합니다.

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

이미지로 이미지 작업 삭제하기

이미지로 이미지 작업을 이미지와 데이터를 포함하여 영구적으로 삭제합니다. 삭제는 취소할 수 없습니다.

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

경로 매개변수

Name
id
Type
path
Description
삭제할 작업의 ID입니다.

작업 상태

PENDING 상태의 작업을 삭제하면 작업을 생성할 때 사용된 크레딧이 환불됩니다.

IN_PROGRESS 상태의 작업은 삭제할 수 없습니다. 요청은 409 Conflict를 반환하며, 작업은 계속 실행됩니다. Meshy는 이미 시작된 작업에 대해서는 환불을 제공하지 않으므로, 이를 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED, 또는 CANCELED 상태가 될 때까지 기다린 후 삭제하세요.

최종 상태(SUCCEEDED, FAILED, 또는 CANCELED)의 작업을 삭제해도 크레딧은 환불되지 않습니다.

반환값

작업이 삭제되면 200 OK를 반환하며, 작업이 IN_PROGRESS 상태인 경우에는 409 Conflict를 반환합니다.

GET/openapi/v1/image-to-image

이미지로 이미지 작업 목록 조회

사용자의 이미지로 이미지 및 텍스트로 이미지 작업 목록을 반환합니다. 각 작업의 type 필드는 두 가지 중 어느 것인지를 나타냅니다.

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

매개변수

Name
page_num
Type
integer
Description
반환할 페이지 번호입니다. 1부터 시작하며 기본값은 1입니다.
Name
page_size
Type
integer
Description
페이지당 작업 수이며, 최대 100까지 가능합니다. 기본값은 10입니다.
Name
sort_by
Type
string
Description
정렬 순서입니다.
사용 가능한 값:
- +created_at: 오래된 순
- -created_at: 최신 순

반환값

이미지로 이미지 작업 객체와 동일한 형식의 페이지네이션된 작업 객체 목록입니다.

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

이미지로 이미지 작업 스트리밍

이미지로 이미지 작업의 업데이트를 서버 전송 이벤트(SSE)로 스트리밍합니다.

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

파라미터

Name
id
Type
path
Description
생성 응답에서 받은 작업 ID입니다.

반환값

이미지로 이미지 작업 객체의 스트림을 서버 전송 이벤트로 반환합니다.

각 이벤트는 Get 엔드포인트가 반환하는 것과 동일한 형태로 전체 작업 객체를 담고 있습니다. 작업이 PENDING 또는 IN_PROGRESS 상태인 동안에는 결과 필드에 아직 값이 없습니다.

이미지로 이미지 작업 객체

이미지로 이미지 작업 객체는 참조 이미지와 텍스트 prompt로부터 생성된 하나의 이미지를 설명합니다. 이 객체는 작업이 성공했을 때의 상태, progress, 이미지를 담고 있습니다.

속성

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
작업 ID입니다. 이 값은 불투명한 문자열로 취급하고, 형식에 의존하지 마세요.
Name
type
Type
string
Description
작업 유형이며, 항상 image-to-image입니다.
Name
ai_model
Type
string
Description
작업에 사용된 AI 모델입니다.
사용 가능한 값:
- 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
편집을 안내한 텍스트 prompt입니다.
Name
status
Type
string
Description
작업 상태이며, PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED 중 하나입니다.
Name
progress
Type
integer
Description
작업이 완료된 정도를 백분율로 나타냅니다. 작업이 시작되기 전까지는 0이며, 성공하면 100이 됩니다.
Name
created_at
Type
timestamp
Description
작업이 생성된 시간이며, 유닉스 밀리초 단위입니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시간이며, 유닉스 밀리초 단위입니다. 작업이 시작되기 전까지는 존재하지 않습니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시간이며, 유닉스 밀리초 단위입니다. 작업이 완료되기 전까지는 존재하지 않습니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간이며, 유닉스 밀리초 단위입니다. 작업이 완료되기 전까지는 존재하지 않습니다.
Name
preceding_tasks
Type
integer
Description
대기열에서 이 작업보다 앞에 있는 작업의 수입니다. 이 값은 작업이 PENDING 상태일 때만 의미가 있습니다. 값이 0일 때는 이 필드가 생략됩니다.
Name
image_urls
Type
array
Description
생성된 이미지의 다운로드 URL입니다. generate_multi_view: true인 경우, 뷰당 하나의 URL을 가지며 보통 세 개입니다. Meshy가 모든 뷰를 분리할 수 없는 경우 더 적은 수를 반환하며, 작업은 여전히 성공한 것으로 처리됩니다. 그렇지 않으면 URL을 하나만 가집니다.
Name
task_error
Type
object
Description
작업이 실패했을 때의 오류 세부 정보입니다. 상태가 FAILED가 아니면 null입니다. 오류를 참고하세요.
Name
consumed_credits
Type
integer
Description
작업에 사용된 크레딧 수입니다. 상태가 PENDING, IN_PROGRESS, SUCCEEDED일 때 존재합니다. FAILED 작업의 경우 Meshy가 작업 실패 시 크레딧을 환불하므로 0입니다.