이미지로 이미지 API

이미지로 이미지 API는 Meshy의 AI 이미지 편집 기능을 귀하의 애플리케이션에 통합할 수 있는 기능입니다. 강력한 AI 모델을 사용하여 참조 이미지와 텍스트 프롬프트로 기존 이미지를 변환하고 편집하세요.

POST/openapi/v1/image-to-image

이미지로 이미지 작업 생성

이 엔드포인트를 사용하여 새로운 이미지로 이미지 작업을 생성할 수 있습니다. 이미지로 이미지 작업 객체에 포함된 속성을 보려면 이미지로 이미지 작업 객체를 참조하십시오.

파라미터

Name
ai_model
Type
string
필수
Description
이미지 생성에 사용할 모델의 ID입니다.
사용 가능한 값:
- nano-banana: 표준 모델 (이미지당 3 크레딧)
- nano-banana-2: 표준보다 강력한 기능을 가진 균형 모델 (이미지당 6 크레딧)
- nano-banana-pro: 향상된 품질의 프로 모델 (이미지당 9 크레딧)
- gpt-image-2: OpenAI GPT Image 2, 고품질 이미지 편집 모델 (이미지당 12 크레딧)
Name
prompt
Type
string
필수
Description
참조 이미지에 적용하고자 하는 변환 또는 편집에 대한 텍스트 설명입니다.
Name
reference_image_urls
Type
array
필수
Description
이미지 편집 작업에 사용할 1에서 5개의 참조 이미지 배열입니다. 현재 .jpg, .jpeg, .png 형식을 지원합니다.
각 이미지를 제공하는 방법은 두 가지가 있습니다:
- 공개적으로 접근 가능한 URL: 인터넷에서 접근 가능한 URL.
- Data URI: 이미지의 base64로 인코딩된 Data URI. Data URI의 예: data:image/jpeg;base64,<your base64-encoded image data>.
Name
generate_multi_view
Type
boolean
기본값 false
Description
true로 설정하면 여러 각도에서 피사체를 보여주는 멀티뷰 이미지를 생성합니다.
generate_multi_view가 true일 때, aspect_ratio 파라미터는 설정할 수 없습니다.
Name
aspect_ratio
Type
string
기본값 1:1
Description
출력 이미지의 종횡비를 지정합니다. 허용되는 값은 선택한 ai_model에 따라 다릅니다:
- 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
사용 가능한 값:
- 1:1: 정사각형 형식
- 16:9: 와이드스크린 가로
- 9:16: 와이드스크린 세로
- 4:3: 표준 가로 (gpt-image-2에서 지원되지 않음)
- 3:4: 표준 세로 (gpt-image-2에서 지원되지 않음)
- 3:2: 가로 (gpt-image-2에서만 지원)
- 2:3: 세로 (gpt-image-2에서만 지원)
Name
remove_background
Type
boolean
기본값 false
Description
true로 설정하면 배경이 제거된 투명한 RGBA PNG로 출력 이미지가 반환되어, 피사체를 원하는 배경에 합성할 수 있습니다.

반환값

응답의 result 속성에는 새로 생성된 이미지로 이미지 작업의 작업 id가 포함됩니다.

실패 모드

Name
400 - Bad Request
Description
요청이 수용할 수 없습니다. 일반적인 원인:
- 파라미터 누락: 필수 파라미터(e.g., ai_model, prompt, reference_image_urls)가 누락됨.
- 잘못된 이미지 형식: 하나 이상의 참조 이미지가 지원되지 않는 형식임.
- 접근 불가능한 URL: 하나 이상의 reference_image_urls를 다운로드할 수 없음.
- 잘못된 파라미터: aspect_ratio가 선택한 ai_model에 허용되지 않는 값임.
- 충돌: generate_multi_view와 aspect_ratio를 동시에 사용할 수 없음.
Name
401 - Unauthorized
Description
인증에 실패했습니다. API 키를 확인하십시오.
Name
402 - Payment Required
Description
이 작업을 수행하기에 충분한 크레딧이 없습니다.
Name
429 - Too Many Requests
Description
속도 제한을 초과했습니다.

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

Response

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

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

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

이 엔드포인트를 사용하면 유효한 작업 id를 제공하여 이미지로 이미지 작업을 가져올 수 있습니다. 이미지로 이미지 작업 객체에 포함된 속성을 보려면 이미지로 이미지 작업 객체를 참조하세요.

매개변수

Name
id
Type
path
Description
가져올 이미지로 이미지 작업의 고유 식별자입니다.

반환값

응답은 이미지로 이미지 작업 객체를 포함합니다. 자세한 내용은 이미지로 이미지 작업 객체 섹션을 확인하세요.

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

이미지로 이미지 작업 삭제

이 엔드포인트는 모든 관련 이미지와 데이터를 포함하여 이미지로 이미지 작업을 영구적으로 삭제합니다. 이 작업은 되돌릴 수 없습니다.

경로 매개변수

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

반환

성공 시 200 OK를 반환합니다.

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

// Returns 200 Ok on success.

GET/openapi/v1/image-to-image

이미지로 이미지 작업 목록

이 엔드포인트를 통해 이미지로 이미지 작업 목록을 검색할 수 있습니다.

매개변수

Name
page_num
Type
integer
Description
페이지네이션을 위한 페이지 번호입니다. 1부터 시작하며 기본값은 1입니다.
Name
page_size
Type
integer
Description
페이지 크기 제한입니다. 기본값은 10 항목입니다. 허용되는 최대값은 50 항목입니다.
Name
sort_by
Type
string
Description
정렬할 필드입니다. 사용 가능한 값:
- +created_at: 생성 시간 오름차순으로 정렬합니다.
- -created_at: 생성 시간 내림차순으로 정렬합니다.

반환값

이미지로 이미지 작업 객체의 페이지네이션된 목록을 반환합니다.

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

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

이 엔드포인트는 Server-Sent Events (SSE)를 사용하여 이미지로 이미지 작업의 실시간 업데이트를 스트리밍합니다.

매개변수

Name
id
Type
path
Description
스트리밍할 이미지로 이미지 작업의 고유 식별자입니다.

반환값

Server-Sent Events로 이미지로 이미지 작업 객체의 스트림을 반환합니다.

PENDING 또는 IN_PROGRESS 작업의 경우, 응답 스트림은 필요한 progress 및 status 필드만 포함합니다.

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

이미지로 이미지 작업 객체

이미지로 이미지 작업 객체는 참조 이미지와 텍스트 prompt 입력을 통해 이미지를 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 이 객체는 다음과 같은 속성을 가지고 있습니다:

속성

Name
id
Type
string
Description
작업의 고유 식별자입니다. 우리는 작업 ID에 대해 k-sortable UUID를 구현 세부사항으로 사용하지만, ID의 형식에 대해 어떠한 가정도 하지 않아야 합니다.
Name
type
Type
string
Description
이미지 생성 작업의 유형입니다. 이미지로 이미지 작업의 경우, 항상 image-to-image가 됩니다.
Name
ai_model
Type
string
Description
이 작업에 사용된 AI 모델입니다. 가능한 값은 nano-banana, nano-banana-2, nano-banana-pro, 또는 gpt-image-2입니다.
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
작업이 생성된 시간의 타임스탬프입니다(밀리초 단위).
타임스탬프는 1970년 1월 1일 UTC 이후 경과된 밀리초 수를 나타내며, RFC 3339 표준을 따릅니다. 예를 들어, 2023년 9월 1일 금요일 오후 12:00:00 GMT는 1693569600000으로 표현됩니다. 이는 Meshy API의 모든 타임스탬프에 적용됩니다.
Name
started_at
Type
timestamp
Description
작업이 시작된 시간의 타임스탬프입니다(밀리초 단위). 작업이 아직 시작되지 않은 경우, 이 속성은 0이 됩니다.
Name
finished_at
Type
timestamp
Description
작업이 완료된 시간의 타임스탬프입니다(밀리초 단위). 작업이 아직 완료되지 않은 경우, 이 속성은 0이 됩니다.
Name
expires_at
Type
timestamp
Description
작업 결과가 만료되는 시간의 타임스탬프입니다(밀리초 단위).
Name
preceding_tasks
Type
integer
Description
이전 작업의 수입니다.
이 필드의 값은 작업 상태가 PENDING일 때만 의미가 있습니다.
Name
image_urls
Type
array
Description
생성된 이미지의 다운로드 가능한 URL 배열입니다. generate_multi_view가 활성화된 경우, 이 배열은 서로 다른 시각 각도를 나타내는 세 개의 이미지 URL을 포함합니다. 그렇지 않으면, 단일 이미지 URL을 포함합니다.
Name
task_error
Type
object
Description
실패한 작업에 대한 오류 세부사항입니다. 전체 task_error 객체 참조는 오류를 참조하십시오.
Name
consumed_credits
Type
integer
Description
이 작업에 소비된 크레딧의 수입니다. 작업 상태가 PENDING, IN_PROGRESS, 또는 SUCCEEDED일 때 나타납니다. FAILED 작업의 경우 0을 반환합니다 (실패 시 크레딧은 환불됩니다).

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
}