텍스트로 이미지 API
텍스트로 이미지 API는 Meshy의 AI 이미지 생성 기능을 여러분의 애플리케이션에 통합할 수 있게 해주는 기능입니다. 강력한 AI 모델을 사용하여 텍스트 프롬프트로부터 고품질 이미지를 생성하세요.
텍스트로 이미지 작업 생성
이 엔드포인트를 사용하면 새로운 텍스트로 이미지 작업을 생성할 수 있습니다. 텍스트로 이미지 작업 객체에 포함된 속성을 확인하려면 텍스트로 이미지 작업 객체를 참고하세요.
파라미터
- 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, 고품질 이미지 모델 (이미지당 9 크레딧)gpt-image-2-5-flare: OpenAI GPT Image 2.5 (Flare), 고품질 이미지 모델 (이미지당 9 크레딧)gpt-image-2-5-sunburst: OpenAI GPT Image 2.5 (Sunburst), 고품질 이미지 모델 (이미지당 9 크레딧)
- Name
- prompt
- Type
- string
- 필수
- Description
생성하려는 이미지에 대한 텍스트 설명입니다. 최상의 결과를 위해 구체적으로 작성하세요.
- Name
- generate_multi_view
- Type
- boolean
- 기본값 false
- Description
true로 설정하면 여러 각도에서 대상을 보여주는 멀티뷰 이미지를 생성합니다.generate_multi_view가true인 경우aspect_ratio파라미터는 설정할 수 없습니다.
- Name
- pose_mode
- Type
- string
- Description
캐릭터 생성을 위한 포즈 mode를 지정합니다. 생략하면 포즈 프리셋 없이 이미지가 생성됩니다.
사용 가능한 값:
a-pose,t-pose
- 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:4gpt-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
사용 가능한 값:
1:1: 정사각형 포맷16:9: 와이드스크린 가로형9:16: 와이드스크린 세로형4:3: 표준 가로형3:4: 표준 세로형3:2: 가로형 (GPT Image 모델에서만 지원)2:3: 세로형 (GPT Image 모델에서만 지원)
- Name
- remove_background
- Type
- boolean
- 기본값 false
- Description
true로 설정하면 배경이 제거된 투명 RGBA PNG 형태로 생성된 이미지가 반환되어, 대상을 원하는 배경에 합성할 수 있습니다.
반환 값
응답의 result 속성에는 새로 생성된 텍스트로 이미지 작업의 작업 id가 포함됩니다.
실패 모드
- Name
400 - Bad Request- Description
요청이 허용되지 않았습니다. 일반적인 원인:
- 파라미터 누락: 필수 파라미터(예:
ai_model,prompt)가 누락되었습니다. - 잘못된 파라미터:
ai_model또는aspect_ratio가 허용된 값 중 하나가 아닙니다. - 충돌:
generate_multi_view와aspect_ratio는 동시에 사용할 수 없습니다.
- 파라미터 누락: 필수 파라미터(예:
- Name
401 - Unauthorized- Description
인증에 실패했습니다. API 키를 확인해 주세요.
- Name
402 - Payment Required- Description
이 작업을 수행하기에 크레딧이 부족합니다.
- Name
429 - Too Many Requests- Description
속도 제한을 초과했습니다.
Request
# Generate an image from a text prompt
curl https://api.meshy.ai/openapi/v1/text-to-image \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"aspect_ratio": "16:9"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Text to Image 작업 검색
이 엔드포인트를 사용하면 유효한 작업 id를 통해 Text to Image 작업을 검색할 수 있습니다.
Text to Image 작업 객체에 포함된 속성을 확인하려면 The Text to Image Task Object를 참조하세요.
매개변수
- Name
- id
- Type
- path
- Description
검색할 Text to Image 작업의 고유 식별자입니다.
반환값
응답에는 Text to Image 작업 객체가 포함됩니다. 자세한 내용은 The Text to Image Task Object 섹션을 확인하세요.
Request
curl https://api.meshy.ai/openapi/v1/text-to-image/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"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입니다.
작업 상태
아직 PENDING 상태인 작업은 삭제되며, 생성 시점에 소모된 크레딧이 환불됩니다.
이미 IN_PROGRESS 상태인 작업은 삭제할 수 없습니다. 요청은 409 Conflict로 거부되며 작업은 계속 실행됩니다. 워커가 이미 시작한 작업에 대한 크레딧은 환불되지 않으므로, 실행 도중에 삭제하면 크레딧과 결과물을 모두 잃게 됩니다. 작업이 SUCCEEDED, FAILED 또는 CANCELED 상태에 도달할 때까지 기다린 다음 삭제하세요.
종료 상태(SUCCEEDED, FAILED 또는 CANCELED)의 작업은 환불 없이 삭제됩니다.
반환값
성공 시 200 OK를 반환하며, 작업이 IN_PROGRESS 상태일 때는 409 Conflict를 반환합니다.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/text-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."
}
Text to Image 작업 목록 조회
이 엔드포인트를 사용하면 Text 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: 생성 시간 기준 내림차순 정렬.
반환값
The Text to Image Task Objects의 페이지네이션된 목록을 반환합니다.
Request
curl https://api.meshy.ai/openapi/v1/text-to-image?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"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=***"
]
}
]
텍스트로 이미지 작업 스트리밍
이 엔드포인트는 Server-Sent Events(SSE)를 사용하여 텍스트로 이미지 작업의 실시간 업데이트를 스트리밍합니다.
매개변수
- Name
- id
- Type
- path
- Description
스트리밍할 텍스트로 이미지 작업의 고유 식별자입니다.
반환값
텍스트로 이미지 작업 객체의 스트림을 Server-Sent Events 형태로 반환합니다.
PENDING 또는 IN_PROGRESS 상태의 작업의 경우, 응답 스트림에는 필요한 progress 및 status 필드만 포함됩니다.
Request
curl -N https://api.meshy.ai/openapi/v1/text-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": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"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=***"
]
}
The Text to Image Task Object
Text to Image Task 객체는 텍스트 prompt 입력으로부터 이미지를 생성하기 위해 Meshy가 추적하는 작업 단위입니다. 이 객체는 다음과 같은 속성을 가지고 있습니다.
Properties
- Name
- id
- Type
- string
- Description
작업의 고유 식별자입니다. 구현 세부 사항으로 작업 id에 k-정렬 가능한 UUID를 사용하지만, id의 형식에 대해 어떠한 가정도 해서는 안 됩니다.
- Name
- type
- Type
- string
- Description
이미지 생성 작업의 유형입니다. Text to Image 작업의 경우 항상
text-to-image입니다.
- Name
- ai_model
- Type
- string
- Description
이 작업에 사용된 AI 모델입니다. 가능한 값은
nano-banana,nano-banana-2,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 PM 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 Text to Image Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-image",
"ai_model": "nano-banana",
"prompt": "A majestic dragon soaring through clouds at sunset",
"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
}