Z Image Turbo는 Novita AI에서 두 개의 비동기 엔드포인트를 통해 사용할 수 있습니다: 표준 텍스트-이미지 생성을 위한 POST https://api.novita.ai/v3/async/z-image-turbo와 LoRA 스타일 모델을 사용한 생성을 위한 POST https://api.novita.ai/v3/async/z-image-turbo-lora입니다. 두 엔드포인트 모두 Novita AI의 표준 비동기 패턴을 따릅니다. 요청을 제출하고 task_id를 받은 다음, 이미지가 준비될 때까지 GET /v3/async/task-result를 폴링합니다. 이 가이드는 첫 번째 요청, 폴링 루프, LoRA 사용법, 그리고 프로덕션 코드를 작성하기 전에 알아야 할 매개변수 참조까지 두 엔드포인트를 처음부터 끝까지 다룹니다.
이 빠른 시작 가이드를 사용해야 하는 경우
Z Image Turbo에 대해 오류 처리, 배치 처리 또는 프로덕션 로직을 추가하기 전에 검증된 작동 요청이 필요할 때 이 가이드를 사용하세요.
Z Image Turbo는 빠른 처리량을 위해 설계되었습니다. 다음과 같은 워크플로우에 적합합니다:
- 최대 품질보다 속도가 더 중요한 경우 — 프로토타입 파이프라인, 배치 미리보기 생성, 또는 지연 시간이 엄격한 제약 조건인 실시간 애플리케이션
- 전체
txt2img매개변수 세트를 구성하지 않고 LoRA 기반 스타일 전송을 원하는 경우. 전용 LoRA 엔드포인트는loras배열을 받아들이고 나머지를 처리합니다. - 최소한의 요청 본문으로 간단한 프롬프트 입력 / 이미지 출력 인터페이스가 필요한 경우
Z Image Turbo는 steps, guidance_scale, sampler_name, negative_prompt, hires_fix, 리파이너 모델 등 전체 Stable Diffusion 구성 표면이 필요할 때는 적합하지 않습니다. 그러한 수준의 제어가 필요하면 표준 POST /v3/async/txt2img 엔드포인트를 사용하세요.
이 가이드는 Novita AI 호스팅 API 경로만 다룹니다. 자체 호스팅이나 파인튜닝은 다루지 않습니다.
1단계: Novita API 키 받기
Novita AI 계정을 만들고 API 키 관리 페이지로 이동하세요. 키를 생성하고 내보냅니다:
export NOVITA_API_KEY="your_api_key_here"
키를 버전 관리, 클라이언트 측 번들, Docker 이미지 레이어에 저장하지 마세요.
2단계: 엔드포인트 확인
Novita AI의 Z Image Turbo는 두 개의 개별 제출 엔드포인트와 하나의 공유 결과 엔드포인트를 사용합니다:
| 기본 T2I | LoRA T2I | |
|---|---|---|
| 제출 | POST https://api.novita.ai/v3/async/z-image-turbo |
POST https://api.novita.ai/v3/async/z-image-turbo-lora |
| 결과 폴링 | GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
GET https://api.novita.ai/v3/async/task-result?task_id=<id> |
| API 참조 | Z Image Turbo 문서 | Z Image Turbo LoRA 문서 |
두 제출 엔드포인트 모두 task_id만 반환합니다. 결과 폴링 엔드포인트는 둘 다 동일합니다. 폴링 루프가 하나에서 작동하면 다른 하나에서도 작동합니다.
3단계: 첫 번째 요청 보내기
기본 엔드포인트는 prompt와 size가 필요합니다. 선택적 매개변수를 추가하기 전에 여기서 시작하세요:
curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A futuristic city skyline at dusk, neon lights, photorealistic, ultra-detailed",
"size": "1024*1024"
}'
성공적인 200 응답은 다음을 반환합니다:
{
"task_id": "abc123..."
}
task_id를 저장하세요. 제출 시 다른 것은 반환되지 않습니다. 생성은 비동기적으로 실행됩니다.
기본 엔드포인트에서 사용 가능한 두 가지 선택적 매개변수:
seed(정수): 재현 가능한 출력을 위한 고정 값. 동일한 프롬프트와 시드 조합은 일관된 결과를 반환합니다.enable_base64_output(부울):true로 설정하면 결과에 호스팅된 URL 대신 base64로 인코딩된 문자열로 이미지가 포함됩니다.
4단계: 결과 폴링하기
쿼리 매개변수로 task_id를 사용하여 작업 결과 엔드포인트에 GET 요청을 보냅니다:
curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
-H "Authorization: Bearer $NOVITA_API_KEY"
완료된 작업은 다음을 반환합니다:
{
"task": {
"task_id": "abc123...",
"status": "TASK_STATUS_SUCCEED",
"progress_percent": 100,
"eta": 0
},
"images": [
{
"image_url": "https://...",
"image_url_ttl": 3600,
"image_type": "png"
}
]
}
task.status가 TASK_STATUS_SUCCEED 또는 TASK_STATUS_FAILED가 될 때까지 1–2초마다 폴링하세요. task.eta 필드는 작업이 여전히 대기열에 있을 때 예상 남은 시간(초)을 제공합니다.
image_url_ttl은 URL의 수명(초)입니다. TTL이 만료되기 전에 이미지를 다운로드하여 저장하세요. 호스팅된 URL은 영구적이지 않습니다.
5단계: 가격, 제한 및 일반적인 오류 확인
Z Image Turbo의 현재 가격은 Novita AI 가격 페이지와 Z Image Turbo 모델 페이지에 나와 있습니다. 가격은 변경될 수 있으므로 비용을 추정하기 전에 요금을 확인하세요.
일반적인 오류:
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| 401 Unauthorized | API 키가 없거나 잘못됨 | 헤더가 Authorization: Bearer <key>인지 확인 |
| 400 Bad Request | 잘못된 요청 본문 | prompt와 size가 문자열인지 확인; seed가 제공된 경우 정수여야 함 |
TASK_STATUS_FAILED |
생성이 거부되거나 오류 발생 | 결과 응답에서 task.reason을 읽어 특정 실패 메시지 확인 |
| 이미지 URL이 403을 반환하거나 만료됨 | TTL 경과 후 URL에 접근 | image_url_ttl 초가 지나기 전에 이미지를 다운로드하여 저장 |
Python 예제
전체 워크플로우 — 제출, 폴링, 이미지 URL 반환:
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def generate_image(prompt: str, size: str = "1024*1024", seed: int = None) -> str:
payload = {"prompt": prompt, "size": size}
if seed is not None:
payload["seed"] = seed
resp = requests.post(
"https://api.novita.ai/v3/async/z-image-turbo",
json=payload,
headers=HEADERS,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
while True:
result = requests.get(
f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
headers=HEADERS,
)
result.raise_for_status()
data = result.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")
time.sleep(1)
if __name__ == "__main__":
url = generate_image(
"A futuristic city skyline at dusk, neon lights, photorealistic",
size="1024*1024",
seed=42,
)
print(url)
LoRA 생성
LoRA 엔드포인트는 요청에 loras 배열을 추가합니다. 각 항목은 path(Novita AI 모델 허브의 LoRA 모델 식별자)와 scale(영향 가중치)을 사용합니다:
curl -s -X POST https://api.novita.ai/v3/async/z-image-turbo-lora \
-H "Authorization: Bearer $NOVITA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a portrait in anime style, soft lighting, detailed face",
"size": "768*1024",
"loras": [
{
"path": "<lora-model-path>",
"scale": 0.8
}
],
"seed": 42
}'
<lora-model-path>를 Novita AI 모델 허브에서 확인된 경로로 바꾸세요. path 형식과 호환 가능한 LoRA 모델은 Z Image Turbo LoRA API 참조에 나와 있습니다. 모델 경로를 추측하지 말고, 확인된 허브 항목만 사용하여 확인되지 않은 경로로 인한 TASK_STATUS_FAILED 결과를 방지하세요.
LoRA 결과 폴링은 기본 엔드포인트와 동일하게 작동합니다.
동일한 LoRA 워크플로우의 Python 버전:
import os
import time
import requests
API_KEY = os.environ["NOVITA_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def generate_with_lora(
prompt: str,
lora_path: str,
lora_scale: float = 0.8,
size: str = "1024*1024",
seed: int = None,
) -> str:
payload = {
"prompt": prompt,
"size": size,
"loras": [{"path": lora_path, "scale": lora_scale}],
}
if seed is not None:
payload["seed"] = seed
resp = requests.post(
"https://api.novita.ai/v3/async/z-image-turbo-lora",
json=payload,
headers=HEADERS,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
while True:
result = requests.get(
f"https://api.novita.ai/v3/async/task-result?task_id={task_id}",
headers=HEADERS,
)
result.raise_for_status()
data = result.json()
status = data["task"]["status"]
if status == "TASK_STATUS_SUCCEED":
return data["images"][0]["image_url"]
if status == "TASK_STATUS_FAILED":
raise RuntimeError(f"Generation failed: {data['task'].get('reason', 'unknown')}")
time.sleep(1)
LoRA scale 가이드
scale은 LoRA 스타일이 적용되는 강도를 제어합니다. 0.8 값이 합리적인 기본값입니다. LoRA 스타일에 의해 프롬프트 세부 정보가 덮어쓰여지는 경우 더 낮게(0.4–0.6) 설정하고, 스타일이 충분히 강하게 나타나지 않는 경우 더 높게(0.9–1.0) 설정하세요. 여러 LoRA를 높은 scale 값으로 쌓으면 일관성이 저하될 수 있으므로 각 LoRA를 개별적으로 먼저 테스트하세요.
일부 LoRA 모델은 스타일을 활성화하기 위해 프롬프트에 트리거 단어가 필요합니다. 테스트하기 전에 Novita AI 허브의 모델 목록에서 필요한 키워드가 있는지 확인하세요.
주요 매개변수
기본 엔드포인트 (/v3/async/z-image-turbo)
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
prompt |
string | 예 | 대상 이미지에 대한 텍스트 설명 |
size |
string | 예 | "width*height" 형식의 출력 크기, 예: "1024*1024" |
seed |
integer | 아니오 | 재현성 고정 값; 동일한 시드 + 프롬프트는 일관된 출력을 반환 |
enable_base64_output |
boolean | 아니오 | true로 설정하면 호스팅된 URL 대신 base64 문자열로 이미지를 반환 |
LoRA 엔드포인트 (/v3/async/z-image-turbo-lora)
| 매개변수 | 유형 | 필수 | 설명 |
|---|---|---|---|
prompt |
string | 예 | 텍스트 프롬프트; 필요한 경우 LoRA 트리거 단어 포함 |
size |
string | 예 | "width*height" 형식의 출력 크기 |
loras |
array | 예 | 하나 이상의 LoRA 객체 |
loras[].path |
string | 예 | Novita AI 모델 허브의 LoRA 모델 경로 |
loras[].scale |
number | 예 | 영향 가중치; 0.8이 일반적인 시작 값 |
seed |
integer | 아니오 | 재현성 고정 값 |
enable_base64_output은 현재 문서의 LoRA 엔드포인트에 나열되지 않습니다. 이미지 검색에는 폴링 결과 URL을 사용하세요.
문제 해결
작업이 예상보다 오래 TASK_STATUS_PENDING 상태로 유지됩니다. 대기열 깊이는 플랫폼 부하에 따라 다릅니다. 폴링 응답의 task.eta 필드는 예상 대기 시간(초)을 반환합니다. 지연 시간에 민감한 프로덕션 경로의 경우 여러 작업 ID에 걸쳐 병렬로 요청을 제출하고 폴링하는 것을 고려하세요.
TASK_STATUS_FAILED가 즉시 또는 잠시 후에 발생합니다. 결과에서 task.reason을 읽으세요. 일반적인 원인: 잘못된 size 문자열 형식, 확인할 수 없는 LoRA path, 또는 콘텐츠 필터링을 트리거한 프롬프트. 최소 요청으로 격리하여 테스트하세요.
이미지 URL이 403을 반환합니다. URL 수명은 image_url_ttl(초)에 의해 제어됩니다. 해당 기간이 지난 후 URL을 요청하면 접근이 거부됩니다. 폴링이 성공한 후 즉시 이미지 데이터를 가져와 저장하세요.
LoRA 스타일이 출력에 나타나지 않습니다. scale을 1.0에 가깝게 높여 보세요. LoRA에 트리거 단어가 필요한지 확인하세요. 필요한 경우 프롬프트에 추가하세요.
LoRA 엔드포인트에서 400 Bad Request. loras 필드가 배열(객체가 아님)인지, 각 항목에 path와 scale이 모두 있는지 확인하세요.
FAQ
Z Image Turbo는 무엇을 위해 설계되었나요?
Z Image Turbo는 빠른 텍스트-이미지 생성을 위해 최적화되었습니다. 빠른 처리량이 필요한 애플리케이션에 적합합니다: 미리보기 생성, 배치 파이프라인, 그리고 전체 SDXL 워크플로우의 세분화된 확산 제어보다 LoRA 기반 스타일화가 더 중요한 사용 사례.
Z Image Turbo는 어떤 크기를 지원하나요?
size 매개변수는 "width*height" 문자열을 사용합니다. 확인된 지원 값은 Z Image Turbo 모델 페이지에 나와 있습니다. 정사각형(1024*1024) 및 세로(768*1024) 형식이 다른 Novita AI 이미지 엔드포인트와 일관된 안전한 시작점입니다.
하나의 요청에 여러 LoRA를 적용할 수 있나요?
loras 배열은 여러 항목을 허용합니다. 실제로 높은 scale 값으로 LoRA를 쌓으면 출력 품질이 저하되는 경우가 많습니다. 각 LoRA를 개별적으로 먼저 테스트한 다음 보수적인 scale 값(항목당 0.5–0.7)으로 결합하세요.
호환되는 LoRA 경로는 어디서 찾을 수 있나요?
Novita AI 모델 허브를 탐색하고 Z Image Turbo LoRA API 참조에서 확인된 경로 형식을 확인하세요. Novita 플랫폼에서 확인하지 않고 외부 소스의 경로를 사용하지 마세요.
negative_prompt가 지원되나요?
현재 문서에서 Z Image Turbo 엔드포인트 모두 negative_prompt 매개변수를 나열하지 않습니다. 주제나 스타일을 제외해야 하는 경우 프롬프트에서 긍정적인 표현을 사용하여 원하지 않는 콘텐츠에서 멀어지도록 유도하거나, negative_prompt를 직접 지원하는 표준 txt2img 엔드포인트를 평가하세요.
단일 호출로 여러 이미지를 생성할 수 있나요?
현재 문서에는 Z Image Turbo 엔드포인트 중 하나에 image_num 매개변수가 나열되어 있지 않습니다. 배치 생성의 경우 여러 요청을 병렬로 제출하고 해당 task_id 값을 동시에 폴링하세요. 각 요청은 독립적입니다.
Z Image Turbo와 표준 txt2img 엔드포인트는 어떻게 비교되나요?
표준 txt2img 엔드포인트는 steps, guidance scale, sampler, negative prompt, Hi-Res Fix, 리파이너 모델 등 광범위한 구성 표면을 지원합니다. Z Image Turbo는 속도와 더 간단한 요청 형태를 위해 해당 구성 가능성을 희생합니다. 매개변수 제어가 중요할 때는 txt2img를 사용하고, 처리량이나 단순성이 우선일 때는 Z Image Turbo를 사용하세요.
