이미지로 이미지 API

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

이 엔드포인트는 이미지를 생성합니다. 손에 쥐거나 출력할 수 있는 오브젝트—사진으로부터 만든 키링, 냉장고 자석, 피규어, 램프 또는 키캡—가 목표라면 Creative Lab APIs(프로토타입 이미지 → 3D 모델 생성)를 사용하세요. 사진 속 대상의 3D 모델을 만드는 것이 목표라면 이미지로 3D를 사용하세요.

POST/openapi/v1/image-to-image

이미지로 이미지 작업 삭제

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

경로 매개변수

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

작업 상태

아직 PENDING 상태인 작업은 삭제되며, 생성 시 소모된 크레딧은 환불됩니다.

이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 후 삭제하세요.

종료 상태(SUCCEEDED, FAILED 또는 CANCELED)의 작업은 환불 없이 삭제됩니다.

반환값

성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태일 때는 409 Conflict를 반환합니다.

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 작업 목록 조회

이 엔드포인트를 사용하면 Image to Image 작업 목록을 조회할 수 있습니다.

매개변수

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

반환값

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

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)를 사용하여 이미지로 이미지 작업의 실시간 업데이트를 스트리밍합니다.

Parameters

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

Returns

이미지로 이미지 작업 객체의 스트림을 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-2-lite, 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
작업이 생성된 시점의 타임스탬프이며, 밀리초 단위입니다.
타임스탬프는 RFC 3339 표준에 따라 1970년 1월 1일 UTC로부터 경과한 밀리초 수를 나타냅니다. 예를 들어, 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
}

이미지로 이미지 API

Create an Image to Image Task

파라미터

반환값

실패 모드

Request

Response

이미지로 이미지 작업 조회

매개변수

반환 값

Request

Response

이미지로 이미지 작업 삭제

경로 매개변수

작업 상태

반환값

Request

Response

Image to Image 작업 목록 조회

매개변수

반환값

Request

Response

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

Parameters

Returns

Request

Response Stream

이미지로 이미지 작업 객체

속성

Example Image to Image Task Object