DeepSeek V4 Flash Vision Exp API 가이드: 제한 사항과 예제

deepseek-v4-flash-vision-exp 엔드포인트는 V4 Flash 제품군에 이미지 입력을 더한다. 다만 이름에 붙은 experimental은 가볍게 볼 표기가 아니다. 공개된 출시 근거만으로는 운영 환경에서의 신뢰성이 입증되지 않았으므로, 기본 모델로 채택하기 전에는 로그를 남기는 파일럿과 대체 경로를 함께 마련하는 편이 안전하다.

30초 만에 판단하는 API 선택 기준

기존 V4 Flash 워크플로에 스크린샷, 차트, 문서 등 이미지를 읽는 기능을 API 호환 방식으로 추가해야 한다면 DeepSeek V4 Flash Vision Exp가 잘 맞는다. 반대로 신원 확인처럼 민감하거나 결과의 책임이 큰 시각 판단이라면, 반드시 별도 검증과 폴백을 유지해야 한다.

정확한 모델 문자열은 deepseek-v4-flash-vision-exp다. DeepSeek는 공식 변경 로그에서 이 모델을 실험적 모델로 분류하며, 2026년 8월 21일부터 API 플랫폼에서 사용할 수 있다고 안내한다. 출시 노트에 따르면 순수 텍스트 기능은 V4 Flash와 동등한 수준이며, 시각 이해가 필요한 에이전트 벤치마크에서는 큰 폭의 개선을 보였다.

Chat Completions로 이미지 한 장 보내기

OpenAI 호환 Chat Completions 요청에서는 user 메시지 안의 content 배열에 텍스트와 이미지를 함께 넣는다. 모델별 동작은 공식 Vision 가이드에 정리되어 있다. 일반 deepseek-v4-flash 모델에 이미지를 보내면 400 오류가 반환된다.

import base64
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

with open("chart.png", "rb") as image_file:
    encoded = base64.b64encode(image_file.read()).decode("utf-8")

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract the three trends from this chart."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{encoded}",
                        "detail": "original",
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

Chat Completions에서는 사용자 메시지의 이미지 입력을 지원한다. 모델이 이미지 맥락과 작업 지시를 한 번에 받도록 이미지와 프롬프트는 반드시 같은 content 배열에 넣는 것이 좋다.

이미지 전달 방식, 이렇게 고르세요

작은 로컬 파일이라면 Base64

로컬에 있는 일회성 이미지는 Base64가 가장 간단하다. 공개 호스팅이 필요 없다는 장점이 있지만, 인코딩된 데이터도 48 MiB 요청 본문 제한에 포함되며 원본 이미지는 32 MiB 이하여야 한다.

사용자나 워커가 한 번 업로드하는 파일에는 적합하지만, 배치 작업에서 반복 사용할 이미지를 위한 방식은 아니다.

호스팅된 에셋은 공개 URL

공개 http 또는 https URL을 쓰면 요청 크기를 작게 유지할 수 있다. 다만 URL은 외부에서 접근 가능해야 하고, 길이는 8,192자 이하여야 하며, 이미지는 60초 안에 다운로드할 수 있고 32 MiB를 넘지 않아야 한다. 비공개 URL, 만료된 URL, 내부 전용 URL은 DeepSeek가 이미지를 가져오기 전에 실패할 수 있다.

재사용하거나 더 큰 파일이면 Files API

Files API로 이미지를 업로드한 뒤, 비전 요청에서 반환된 ID를 참조하면 된다.

{
  "type": "file",
  "file_id": "file-api-xxxxxxxxxxxxxxxx"
}

참조 파일은 이미지당 최대 64 MiB까지 가능하며, 매 요청마다 같은 바이트를 다시 업로드할 필요가 없다. 대신 업로드와 파일 수명 관리 단계가 하나 더 생긴다. 반환된 ID는 공개 공유 링크처럼 다루지 말고, 생성에 사용한 키와 함께 관리해야 한다.

파일이 32 MiB보다 크거나, 요청 크기가 48 MiB를 넘길 가능성이 있거나, 여러 에이전트 단계에서 같은 이미지를 살펴봐야 한다면 Files API가 실용적인 선택이다.

비용이 나가기 전 이미지 세부 정보 조절하기

detail 필드는 image_url 입력과 Responses API 이미지 파트에서 사용할 수 있다. 아래 동작은 DeepSeek의 공식 Vision 가이드를 기준으로 한다.

DeepSeek는 추론 전에 이미지를 리사이즈한다. Vision 가이드에 따르면 이미지 한 장의 상한은 이미지 토큰 384개이며, 이미지는 각각 독립적으로 계산된다. 따라서 매우 큰 원본이라도 리사이즈 후 이미지 토큰 사용량이 비례해서 늘어나는 것은 아니다. 다만 파일이 크면 여전히 업로드 및 요청 크기 제한에 걸릴 수 있다.

공식 Models & Pricing 페이지에 따르면 deepseek-v4-flash-vision-exp의 토큰 단가는 V4 Flash와 같다. 비혼잡 시간 기준 캐시된 입력 토큰은 100만 토큰당 $0.007, 캐시 미스 입력 토큰은 $0.22이며, 피크 시간에는 각각 $0.014와 $0.44다. 출력은 비혼잡 시간에 $0.66, 피크 시간에 $1.32다. 이미지 토큰도 입력 토큰으로 과금되므로, 비용을 추정할 때 이미지 수와 detail 설정을 함께 반영해야 한다.

실제 API 오류로 이어지는 제한 사항

특히 놓치기 쉬운 제한이 두 가지 있다. 이미지를 받을 수 있는 모델은 deepseek-v4-flash-vision-exp뿐이며, Chat Completions에서 system 또는 assistant 메시지에 이미지 블록을 넣으면 실패한다. 비전 모델이 아닌 모델에 이미지를 보내면 DeepSeek는 400 오류 메시지로 This model does not support image가 반환된다고 문서화하고 있다.

세 가지 API 인터페이스에서 쓰는 같은 모델

DeepSeek는 Vision 가이드에서 이 모델을 다음 세 인터페이스로 설명한다.

세 인터페이스 모두 Base64, 공개 URL, Files API 참조를 지원하지만 content 타입은 서로 다르다. Chat Completions용 블록을 그대로 Responses API에 복사해서는 안 된다.

출시 자료가 말해 주는 것과 말해 주지 않는 것

DeepSeek의 8월 21일 변경 로그는 강력한 출시 벤치마크를 제시한다. p0.95 기준 Terminal Bench 2.1은 83.9, Chartography는 64.3이다. 하지만 이는 공급업체가 보고한 결과이지 독립적으로 재현된 결과는 아니다. 출시 자료는 텍스트 전용 V4 Flash가 두 가지 시각 평가에서 멀티모달 요소를 무시한다고도 명시한다.

출시 벤치마크는 공급업체가 보고한 수치이므로, 운영 트래픽을 연결하기 전에는 애플리케이션에서 중요한 시각 작업을 직접 검증해야 한다.

운영 환경에 바로 써도 될까?

스크린샷 분석, 차트 정보 추출, 문서 분류, 시각 상태를 확인해야 하는 에이전트가 주된 워크로드라면 DeepSeek V4 Flash Vision Exp를 통제된 파일럿으로 도입해 볼 만하다. Flash와 동일한 가격 체계, 세 가지 입력 경로, 이미지당 384토큰 상한 덕분에 평가 비용 모델을 구체적으로 세우기도 쉽다.

모델이 여전히 실험적이고, 인용한 출시 근거 역시 이런 사례의 신뢰성을 입증하지 않으므로 신원 확인, 안전 판단, 의료 해석 등 결과의 영향이 큰 시각 판단에는 단독 백엔드로 쓰지 말아야 한다. 같은 인터페이스 뒤에 폴백을 두고, 이미지 출처, detail 설정, 입력·출력 사용량, 지연 시간, 재시도, 작업 성공 여부를 기록하자.

운영 트래픽을 연결하기 전에 최소한 다음 항목은 테스트하는 것이 좋다.

1. low 및 original detail에서 스크린샷의 작은 텍스트.
2. 레이블, 범례, 촘촘한 축이 있는 차트.
3. 한 요청에 여러 이미지를 넣는 경우.
4. 비공개이거나 응답이 느린 이미지 URL.
5. 시각 검토 이후의 도구 호출.
6. 틀렸거나 모호한 신원 확인 프롬프트.
7. 400 오류, 타임아웃, 잘못된 이미지 응답 이후의 폴백 동작.

DeepSeek V4 Flash Vision Exp API FAQ

정확한 모델명은 무엇인가요?

deepseek-v4-flash-vision-exp를 사용하면 된다. DeepSeek의 2026년 8월 21일 변경 로그에서는 이 모델을 API 플랫폼의 실험적 멀티모달 모델로 소개한다.

V4 Flash와 가격이 같은가요?

그렇다. DeepSeek 가격 페이지는 Vision Exp와 V4 Flash에 동일한 캐시 히트, 캐시 미스, 출력 토큰 단가를 제시한다. 이미지 토큰은 리사이즈 후 이미지당 최대 384토큰까지 입력 토큰으로 과금된다.

이미지도 생성할 수 있나요?

공식 Vision 가이드는 이미지 생성이 아니라 이미지 이해 기능을 문서화한다. DeepSeek가 별도의 생성 지원을 발표하기 전까지는 이 엔드포인트를 이미지 이해 전용으로 보는 것이 맞다.

왜 요청이 400 오류를 반환하나요?

모델 문자열, 메시지 역할, content 블록 타입, 파일 크기, 이미지 형식을 확인해 보자. 비전 모델이 아닌 모델에 이미지를 보내거나 지원하지 않는 메시지 역할에 이미지를 배치하면, 문서에 나온 This model does not support image 오류가 발생할 수 있다.