대부분의 비전 모델은 선택을 요구합니다. 이미지를 보낼 수도 있고 많은 텍스트를 보낼 수도 있지만, 한 가지를 잘하는 모델은 다른 것을 잘하지 못하는 경우가 많습니다.
GLM-5.3-Flash는 여러분에게 선택을 강요하지 않습니다. 이 모델은 1,048,576 토큰의 컨텍스트 창 내에서 다른 모든 요청과 동일하게 이미지를 콘텐츠 블록으로 받아들입니다. 기본 이미지 입력과 100만 토큰의 여유 공간이라는 이 조합은 단일 기능으로는 불가능했던 새로운 워크플로를 가능하게 합니다.
이 가이드에서는 페이로드, 구축할 가치가 있는 워크플로, 그리고 아직 검증되지 않은 부분들을 다룹니다.
어댑터 기반이 아닌 기본(Native) 방식
Z.ai의 이전 비전 작업은 별도의 모델로 제공되었습니다. GLM-5V-Turbo와 GLM-4.6V는 별개의 모델 ID를 가진 별개의 엔드포인트였으며, 이를 사용한다는 것은 텍스트 트래픽과 다른 곳으로 이미지 트래픽을 라우팅해야 한다는 것을 의미했습니다. 이 모델의 더 큰 형제인 GLM-5.3은 이미지를 기본으로 처리하기보다는 어댑터를 통해 비전을 라우팅합니다.
GLM-5.3-Flash는 GLM-5 시리즈 중 이미지가 동일한 호출에서 동일한 컨텍스트를 공유하며 동일한 모델에 대한 1등 입력으로 사용되는 첫 번째 모델입니다.
실질적으로 이는 하나의 모델 ID, 하나의 청구 항목, 하나의 속도 제한 세트, 그리고 가장 중요하게는 이미지와 텍스트를 동시에 담는 하나의 컨텍스트 창을 의미합니다. 이전 경로를 유지하고 있다면, GLM-5V-Turbo API 가이드 및 GLM-4.6V 가이드에서 해당 모델들을 다룹니다.
페이로드
이미지 입력은 유형이 지정된 콘텐츠 블록을 통해 작동합니다. `content`가 문자열 대신 배열이 됩니다:
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ZAI_API_KEY"],
base_url="https://api.z.ai/api/paas/v4/",
)
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What is wrong with this layout on mobile?"},
{
"type": "image_url",
"image_url": {"url": "https://example.com/mobile-view.png"},
},
],
}
],
)
print(response.choices[0].message.content)
로컬 또는 비공개 이미지의 경우 base64 데이터 URL을 사용합니다:
import base64
from pathlib import Path
def image_block(path: str) -> dict:
data = base64.b64encode(Path(path).read_bytes()).decode("utf-8")
suffix = Path(path).suffix.lstrip(".").replace("jpg", "jpeg")
return {
"type": "image_url",
"image_url": {"url": f"data:image/{suffix};base64,{data}"},
}
여러 이미지는 여러 블록을 의미합니다. URL의 단축 배열은 없습니다:
content = [
{"type": "text", "text": "Image 1 is the design. Image 2 is what we built. List the differences."},
image_block("design.png"),
image_block("built.png"),
]
순서가 중요합니다. 모델은 배열을 순서대로 읽으므로, 참조하는 이미지 앞에 틀을 잡는 텍스트를 넣고, 여러 이미지를 보낼 때 명시적으로 레이블을 지정해야 합니다. "이미지 1은 디자인입니다"와 같은 문구는 모델이 답변을 연결할 무언가를 제공합니다.
기본 설정 및 인증은 API 가이드에서 다룹니다.
구축할 가치가 있는 워크플로
스크린샷 디버깅
명확하고, Z.ai가 의지하는 방식입니다. 자체 자료에서는 모델이 "인터페이스, 렌더링 결과, 상호작용 피드백"을 관찰한다고 설명하는데, 이는 사진 설명보다는 코딩 에이전트의 관점입니다.
깨진 렌더링과 그것을 생성한 소스를 동일한 요청으로 보냅니다:
content = [
{"type": "text", "text": "This component renders incorrectly below 400px. Here is the screenshot and the source."},
image_block("bug-mobile.png"),
{"type": "text", "text": f"```jsx\n{component_source}\n```"},
]
모델은 여러분의 설명이 아니라 실제 렌더링에 대해 추론합니다. 이는 시각적 문제를 인간이 말로 번역하는 대부분의 프론트엔드 디버깅 대화에서 가장 손실이 큰 단계를 제거합니다.
디자인 비교
두 이미지와 질문. 시각적 회귀에 대한 소프트 체크로서 CI에서 유용하며, diff 도구가 픽셀 변경을 알려주고 모델은 변경 사항이 중요한지 여부를 알려줍니다.
여기서 신뢰성에 대해 현실적으로 생각해야 합니다. 스크린샷을 비교하는 모델은 단언이 아니라 판단입니다. 배포를 단독으로 차단하는 대신, 인간이 검토해야 할 diff를 분류하는 데 사용하세요.
문서와 사양서 함께 사용
이것이 1M 컨텍스트가 그 역할을 하는 지점입니다. 긴 사양서를 텍스트로 프롬프트에 넣고 렌더링된 결과물을 이미지로 넣은 다음, 두 가지가 일치하는지 묻습니다.
content = [
{"type": "text", "text": f"Specification:\n\n{spec_text}"},
{"type": "text", "text": "Below is the generated report. Does it satisfy every requirement above? List gaps."},
image_block("generated-report.png"),
]
40페이지짜리 사양서와 이미지를 하나의 프롬프트에 넣는 것은 128K 창과 어댑터 기반 비전을 가진 모델로는 할 수 없는 일입니다. 이것이 바로 실제 새로운 기능입니다.
Z.ai의 릴리스 노트는 또한 이 모델의 에이전트 행동을 위한 목표로 사무 문서 및 금융 연구 워크플로를 언급합니다.
차트 및 대시보드
차트 이미지를 읽고 구조화된 데이터를 반환하는 것은 표준 추출 작업입니다. JSON을 요청하고 유효성을 검사합니다:
content = [
{"type": "text", "text": "Extract the series in this chart as JSON: [{label, values: [...]}]. Return only JSON."},
image_block("quarterly.png"),
]
신뢰하기보다는 스키마에 대해 출력을 검증합니다. 차트 읽기는 모델이 확신에 차서 잘못된 숫자를 생성하는 작업의 종류이며, 구조적 유효성 검사는 값 오류를 잡아내지 못하더라도 형태 오류를 잡아냅니다.
전용 문서 추출의 경우, 전문가가 여전히 일반론자를 이길 수 있습니다. 문서 이해를 위한 GLM-OCR이 해당 경로를 다룹니다.
비디오 및 파일
Z.ai의 문서는 이미지와 함께 비디오 및 파일 입력을 동일한 콘텐츠 블록 메커니즘을 사용하여 나열합니다.
이 점에 주의하십시오. 이 모델의 비디오 지원은 새롭고, 문서화가 미흡하며, 많은 사람들이 이미 사용해 본 이미지 입력에 비해 공개적으로 거의 사용되지 않았습니다. 공급업체 지원 또한 다릅니다. 모델 기능은 호출하는 게이트웨이에서 사용 가능한 기능과 동일하지 않습니다.
비디오가 애플리케이션에 중요하다면, 설계하기 전에 자체 미디어 및 자체 공급업체에 대해 직접 테스트하십시오. 기능 표의 한 줄을 작동하는 기능으로 취급하지 마십시오.
취약점
네이티브 다중 모달리티가 안정적인 다중 모달리티와 같은 것은 아닙니다. 무엇인가를 출시하기 전에 알아두어야 할 네 가지 실패 모드가 있습니다.
차트에서 나오는 확신에 찬 숫자. 플로팅된 선에서 값을 읽는 것은 유창하고 정확하게 포맷된, 하지만 틀린 답변을 생성할 가능성이 가장 높은 작업입니다. 스키마 유효성 검사는 잘못된 출력을 잡아내지만, 그저 잘못된 그럴듯한 숫자를 잡아낼 수는 없습니다. 숫자가 중요하다면, 그림이 아니라 기본 데이터에서 가져오십시오.
작은 텍스트. 고밀도 UI 스크린샷, 저해상도 캡처의 테이블, 압축된 이미지의 코드는 모두 품질이 저하됩니다. 토큰을 절약하기 위해 다운스케일링하면 문제가 더욱 심해지므로, 비용 레버와 정확성 사이에는 직접적인 갈등이 있습니다. 전체 프레임을 축소하는 대신 관심 영역을 잘라내십시오.
공간 정밀도. 모델은 레이아웃을 잘 설명하지만 측정은 잘 못합니다. "버튼이 입력 상자와 겹칩니다"는 보통 맞습니다. "버튼이 왼쪽으로 12픽셀 너무 멀리 떨어져 있습니다"는 보통 틀립니다.
순서 및 참조 혼동. 한 요청에 여러 이미지가 있을 때, 모델은 세부 사항을 잘못된 이미지에 귀속시킬 수 있습니다. 텍스트 블록에서 명시적으로 레이블을 지정하고, 정밀도가 중요할 때는 개수를 낮게 유지하십시오.
이러한 문제 중 어느 것도 GLM-5.3-Flash에만 국한된 것은 아닙니다. 이는 비전 언어 모델의 표준적인 한계이며, 57 Intelligence Index 점수도 이를 면제하지 않습니다. 잘못된 답변이 실행되지 않고 잡히도록 워크플로를 설계하십시오.
비용
이미지는 컨텍스트 토큰을 소비하며 입력으로 청구됩니다. 별도의 이미지 추가 요금은 없습니다.
정가 기준으로 백만 입력 토큰당 $0.15이며, 2026년 9월 9일까지 진행되는 출시 할인 기간 동안에는 $0.075입니다. 고해상도 이미지는 상당한 수의 토큰을 소비하므로, 해상도는 비용 레버입니다. 세부 사항이 요청의 핵심이 아니라면 전송하기 전에 다운스케일링하십시오.
`reasoning_effort`는 기본값이 `max`이며, 이는 추론을 출력 토큰으로 청구합니다. 이미지에서 직접적인 추출의 경우, `low`가 보통 올바른 설정이며 실질적으로 더 저렴합니다. 가격 분석에서 두 가지 레버를 모두 다룹니다.
이미지 비용 관리하기
이미지는 입력 토큰으로 청구되므로, 해상도는 직접적인 비용 레버이며, 명백한 최적화는 위의 정확도 노트와 상충됩니다.
실용적인 작업 순서:
- 확대하기 전에 자르십시오. 전체 화면을 절반으로 보내는 것보다 관련 영역을 전체 해상도로 보내는 것이 더 좋습니다. 모델이 필요 없는 컨텍스트를 제거하고 필요한 세부 정보를 유지합니다.
- 질문에 해상도를 맞추십시오. "레이아웃이 깨졌습니까?"는 공격적인 다운스케일링에서도 살아남습니다. "이 오류 메시지가 무엇을 의미합니까?"는 그렇지 않습니다.
- 변경되지 않은 이미지를 다시 보내지 마십시오. 다중 턴 대화에서 한 번 보낸 이미지는 이미 컨텍스트에 있습니다. 매 턴마다 다시 첨부하면 매 턴마다 비용을 지불하게 됩니다.
- `reasoning_effort`를 의도적으로 설정하십시오. 기본값은 `max`이며, 추론은 출력으로 청구됩니다. 간단한 추출에는 거의 필요하지 않습니다.
각 응답의 `usage` 객체는 호출당 실제 토큰 수를 제공하며, 이는 파일 크기만으로 추측하는 대신 이미지가 실제로 얼마의 비용이 들었는지 알아낼 수 있는 유일한 방법입니다.
다중 모달리티 호출 테스트
다중 모달리티 요청은 수동으로 테스트하기에 불편합니다. base64 데이터 URL은 수천 자에 달하여 curl 명령을 읽을 수 없게 만들고 편집하여 다시 실행하는 것을 사실상 불가능하게 만듭니다. 응답은 자유 형식 텍스트이므로 회귀를 놓치기 쉽습니다.
두 가지 습관이 도움이 됩니다. 동작이 변경될 때 알 수 있도록 작고 고정된 참조 이미지 세트와 예상 답변을 유지하십시오. 그리고 구조화된 추출을 육안으로 확인하는 대신 스키마에 대해 검증하십시오.
Apidog는 이를 위한 실용적인 본거지입니다. 셸 명령 대신 저장된 요청에 이미지 페이로드를 저장하고, API 키를 환경 변수로 유지하며, 추출 프롬프트가 반환하는 JSON에 어설션을 첨부하십시오. 모델을 전환하거나 공급업체가 무언가를 업데이트할 때, 스위트를 다시 실행하면 사용자가 발견하기를 기다리는 대신 비전 경로가 여전히 제대로 작동하는지 알 수 있습니다.
FAQ
GLM-5.3도 이미지를 지원합니까? 기본적으로 지원하지 않습니다. GLM-5.3은 별도의 어댑터를 통해 비전을 라우팅합니다. Flash는 기본 다중 모달 모델이며, 이는 비교 문서에서 다룹니다.
요청당 몇 개의 이미지가 가능합니까? 여러 개가 가능하며, 각각 고유한 `image_url` 블록으로 구성됩니다. 실제 한계는 컨텍스트 예산입니다.
URL 또는 base64? 둘 다 작동합니다. 이미 호스팅되어 접근 가능한 경우 공개 URL을 사용하고, 로컬 또는 비공개 이미지의 경우 base64를 사용하십시오.
비디오도 허용합니까? Z.ai는 비디오 입력을 문서화하지만, 새롭고 거의 사용되지 않았습니다. 먼저 자체 미디어 및 공급업체에 대해 확인하십시오.
이미지 비용은 다르게 청구됩니까? 추가 요금은 없습니다. 입력 토큰을 소비하므로 해상도가 비용에 영향을 미칩니다.