Ling 3.0 Flash VL은 Novita AI의 OpenAI 호환 API를 통해 텍스트, 이미지 및 비디오 입력을 수용합니다. 기본 URL에 https://api.novita.ai/openai를 설정하고, 모델 ID로 inclusionai/ling-3.0-flash-vl을 사용하며, 표준 채팅 완성 메시지에 이미지 URL 또는 데이터 URL을 포함시키세요. 이 가이드는 설정, 이미지 요청, 비디오 워크플로우, 함수 호출, 추론 제어 및 프로덕션 확인에 중점을 둡니다.
모델 포지셔닝, 가용성 및 카탈로그 컨텍스트에 대한 자세한 내용은 Novita AI의 Ling 3.0 Flash VL: 출시, 기능 및 가격을 참조하세요. 텍스트 전용 통합의 경우, 이 가이드를 Ling 3.0 Flash API 빠른 시작과 비교해 보세요.
필요 사항
| 항목 | 값 |
|---|---|
| API 키 | NOVITA_API_KEY에 저장된 Novita AI API 키 |
| OpenAI 호환 기본 URL | https://api.novita.ai/openai |
| 채팅 완성 엔드포인트 | POST https://api.novita.ai/openai/v1/chat/completions |
| 모델 ID | inclusionai/ling-3.0-flash-vl |
Novita AI LLM 가이드는 OpenAI 호환 클라이언트 설정을 설명합니다. 비전-언어 가이드는 content 배열 형식, image_url 항목, 이미지 세부 정보 및 base64 데이터 URL을 설명합니다. 2026년 9월 9일에 확인된 모델 페이지에는 텍스트, 이미지 및 비디오 입력, 텍스트 출력, 함수 호출, 추론, 256K 컨텍스트 창 및 최대 32K 출력이 나열되어 있습니다.
소스 코드에 키를 직접 넣지 말고 셸에서 키를 내보내세요:
export NOVITA_API_KEY="your_api_key"
Python 이미지 요청
OpenAI Python SDK는 사용자 메시지의 content에 대한 배열을 허용합니다. 시각적 입력을 먼저 배치하고, 명령어를 별도의 텍스트 항목으로 추가하세요.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/receipt.jpg",
"detail": "high",
},
},
{
"type": "text",
"text": "Extract the merchant, date, and total. If a field is not legible, say so.",
},
],
}
],
max_tokens=256,
temperature=0.2,
)
print(response.choices[0].message.content)
detail은 low, high 또는 auto가 될 수 있습니다. 작은 텍스트와 미세한 시각적 세부 정보에는 high를 사용하고, 지연 시간이 중요할 때는 low 또는 auto로 시작하세요. 이미지 입력은 토큰화되어 텍스트와 함께 계산되므로, 대표 이미지에서 비용과 품질을 측정하세요.
cURL 이미지 요청
동일한 페이로드가 셸 스크립트에서도 작동합니다. --fail-with-body는 HTTP 오류를 표시하면서 0이 아닌 종료 상태를 반환합니다.
curl --fail-with-body "https://api.novita.ai/openai/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${NOVITA_API_KEY}" \
-d '{
"model": "inclusionai/ling-3.0-flash-vl",
"messages": [
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://example.com/diagram.png",
"detail": "auto"
}
},
{
"type": "text",
"text": "Describe the main components and their connections."
}
]
}
],
"max_tokens": 512,
"temperature": 0.2
}'
개인 로컬 이미지의 경우, 원격 URL 대신 data:image/jpeg;base64,<base64_image_bytes>와 같은 데이터 URL을 사용하세요. MIME 유형을 인코딩된 파일과 일치시키고, 개인 이미지가 포함된 요청 본문을 로깅하지 마세요.
비디오 입력 처리
현재 Ling 3.0 Flash VL 모델 목록에는 입력 모달리티 중 비디오가 포함되어 있습니다. 공개 Novita 비전 가이드는 위의 이식 가능한 OpenAI 호환 이미지 페이로드를 문서화하지만, 별도의 일반 video_url 메시지 스키마는 정의하지 않습니다. 프로덕션 클라이언트에서 이를 임의로 생성하지 마세요.
이식 가능한 비디오 이해 워크플로우의 경우, 대표 프레임을 추출하고 여러 image_url 항목으로 전송한 후 프롬프트에 타임스탬프를 포함하세요. 비전 가이드에서는 요청당 두 개 이하의 이미지를 권장하므로, 짧은 윈도우를 샘플링하거나 여러 번 호출하세요:
ffmpeg -ss 00:00:05 -i input.mp4 -vf "fps=1/5,scale=1280:-2" -frames:v 2 frame-%02d.jpg
결과 프레임은 Python 또는 cURL 페이로드에서 이미지 항목을 반복하여 전송할 수 있습니다. 계정의 현재 API 참조에 네이티브 비디오 콘텐츠 형태가 노출되는 경우, 해당 참조를 따르고 먼저 작은 클립으로 검증하세요. 모델 목록은 비디오 기능을 확인하지만, 전송 형식은 통합 시점의 실시간 API 문서와 대조하여 확인해야 합니다.
시각적 컨텍스트를 사용한 함수 호출
함수 호출은 모델이 본 내용을 애플리케이션 동작으로 전환해야 할 때 유용합니다. 도구를 좁게 유지하고 그 인수를 애플리케이션 코드에서 검증하세요.
tools = [
{
"type": "function",
"function": {
"name": "flag_document",
"description": "Send a document for manual verification.",
"parameters": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Why review is needed."},
"page_or_frame": {"type": "string", "description": "Page or video timestamp."},
},
"required": ["reason"],
},
},
}
]
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/document.jpg"}},
{"type": "text", "text": "Flag this document if key fields are unclear."},
],
}
],
tools=tools,
tool_choice="auto",
max_tokens=256,
temperature=0.1,
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
print(call.function.name, call.function.arguments)
else:
print(message.content)
도구 인수는 신뢰할 수 없는 모델 출력으로 취급하세요. JSON을 검증하고, 권한을 확인하며, 함수를 모델 외부에서 실행하세요. 시각적 관찰만으로는 워크플로우에 필요한 검사 없이 되돌릴 수 없는 작업을 직접 트리거해서는 안 됩니다.
추론 제어
Novita의 OpenAI 호환 채팅 완성 API는 enable_thinking 및 separate_reasoning 필드를 포함하며, Ling 3.0 Flash VL 목록에는 추론 지원이 포함되어 있습니다. 프로덕션 래퍼에 추가하기 전에 작은 요청으로 이러한 필드를 테스트하세요:
response = client.chat.completions.create(
model="inclusionai/ling-3.0-flash-vl",
messages=[
{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}},
{"type": "text", "text": "Compare the two trends and state which one needs investigation."},
],
}
],
enable_thinking=True,
separate_reasoning=True,
max_tokens=512,
temperature=0.2,
)
print(response.choices[0].message)
추론 출력은 응답 구문 분석 및 지연 시간을 변경할 수 있습니다. 애플리케이션이 캡션이나 도구 호출만 필요한 경우 이러한 필드를 생략하고 먼저 더 간단한 요청과 품질을 비교하세요.
통합 체크리스트
스모크 테스트를 넘어가기 전에:
- 표시 이름이 아닌 정확한 모델 ID와 엔드포인트를 확인하세요.
- 공개 이미지 URL을 테스트한 다음 base64 데이터 URL을 테스트하고, 개인 이미지 처리를 별도로 검증하세요.
max_tokens를 제한하고, 불필요한 이미지 콘텐츠를 유지하지 않고 사용량 및 지연 시간을 로깅하세요.- 작은 텍스트, 차트 및 일반 사진에 대한 이미지 세부 정보 설정을 테스트하세요.
- 실행 전에 도구 인수를 검증하고 도구 호출이 없는 응답을 처리하세요.
- 비디오 워크플로우의 경우, 프레임 샘플링, 타임스탬프 추적 및 실시간 API 참조에서 지원하는 네이티브 비디오 페이로드를 정의하세요.
- 프로덕션 전에 모델 가용성, 가격 및 제한을 재확인하세요. 카탈로그 값은 변경될 수 있습니다.
FAQ
어떤 모델 ID를 사용해야 하나요?
inclusionai/ling-3.0-flash-vl을 사용하세요. Ling 3.0 Flash VL은 표시 이름이며 요청 값이 아닙니다.
이 가이드는 어떤 엔드포인트를 사용하나요?
SDK 기본 URL로 https://api.novita.ai/openai를 사용하거나 cURL 요청을 https://api.novita.ai/openai/v1/chat/completions으로 전송하세요.
이미지를 어떻게 보내나요?
사용자 메시지에 image_url 항목과 text 항목이 있는 content 배열을 추가하세요. 이미지 URL은 접근 가능한 이미지를 가리키거나 base64 데이터 URL을 사용할 수 있습니다.
모델이 비디오를 수용하나요?
2026년 9월 9일에 확인된 Novita 모델 목록에는 비디오가 입력 모달리티로 나열되어 있습니다. 공개 비전 가이드는 일반적인 직접 비디오 메시지 형태를 문서화하지 않으므로, 네이티브 비디오 페이로드를 보내기 전에 실시간 API 참조를 확인하세요. 프레임 샘플링 워크플로우가 이식 가능한 대체 방법입니다.
함수 호출 및 추론을 지원하나요?
현재 Novita 목록에는 두 기능이 모두 포함되어 있습니다. 위의 예제는 tools, enable_thinking 및 separate_reasoning을 보여줍니다. 자체 워크로드로 응답 형태와 지연 시간을 테스트하세요.
