O Ling 3.0 Flash VL aceita entradas de texto, imagem e vídeo através da API compatível com OpenAI da Novita AI. Defina https://api.novita.ai/openai como a URL base, use inclusionai/ling-3.0-flash-vl como o ID do modelo e coloque uma URL de imagem ou URL de dados em uma mensagem padrão de chat completions. Este guia aborda configuração, requisições de imagem, workflows de vídeo, function calling, controles de raciocínio e verificações de produção.
Para posicionamento do modelo, disponibilidade e contexto de catálogo, veja Ling 3.0 Flash VL na Novita AI: Lançamento, Capacidades e Preços. Para uma integração somente de texto, compare este guia com o Início Rápido da API Ling 3.0 Flash.
O Que Você Precisa
| Item | Valor |
|---|---|
| Chave de API | Uma chave de API da Novita AI em NOVITA_API_KEY |
| URL base compatível com OpenAI | https://api.novita.ai/openai |
| Endpoint de chat completions | POST https://api.novita.ai/openai/v1/chat/completions |
| ID do modelo | inclusionai/ling-3.0-flash-vl |
O guia de LLM da Novita AI documenta a configuração do cliente compatível com OpenAI. O guia de visão-linguagem documenta o formato do array content, entradas image_url, detalhe de imagem e URLs de dados base64. A página do modelo verificada em 9 de setembro de 2026 lista entrada de texto, imagem e vídeo, saída de texto, function calling, raciocínio, uma janela de contexto de 256K e uma saída máxima de 32K.
Exporte a chave no seu shell em vez de colocá-la no código fonte:
export NOVITA_API_KEY="sua_chave_api"
Requisição de Imagem em Python
O SDK Python da OpenAI aceita um array para o content da mensagem do usuário. Coloque a entrada visual primeiro, depois adicione a instrução como um item de texto separado.
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": "Extraia o comerciante, a data e o total. Se um campo não estiver legível, informe.",
},
],
}
],
max_tokens=256,
temperature=0.2,
)
print(response.choices[0].message.content)
detail pode ser low, high ou auto. Use high para textos pequenos e detalhes visuais finos; comece com low ou auto quando a latência for importante. A entrada de imagem é tokenizada e contada junto com o texto, então meça o custo e a qualidade em imagens representativas.
Requisição de Imagem com cURL
O mesmo payload funciona a partir de um script shell. --fail-with-body mantém as falhas HTTP visíveis enquanto retorna um código de saída diferente de zero.
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": "Descreva os principais componentes e suas conexões."
}
]
}
],
"max_tokens": 512,
"temperature": 0.2
}'
Para uma imagem local privada, substitua a URL remota por uma URL de dados como data:image/jpeg;base64,<base64_image_bytes>. Mantenha o tipo MIME alinhado com o arquivo codificado e não registre corpos de requisição contendo imagens privadas.
Manipulando Entradas de Vídeo
A listagem atual do modelo Ling 3.0 Flash VL inclui vídeo entre suas modalidades de entrada. O guia público de visão da Novita documenta o payload de imagem portátil compatível com OpenAI acima, mas não define um esquema de mensagem video_url genérico separado. Não invente um em um cliente de produção.
Para um workflow portátil de compreensão de vídeo, extraia quadros representativos, envie-os como múltiplos itens image_url e inclua timestamps no prompt. O guia de visão recomenda no máximo duas imagens por requisição, então amostre janelas curtas ou faça múltiplas chamadas:
ffmpeg -ss 00:00:05 -i input.mp4 -vf "fps=1/5,scale=1280:-2" -frames:v 2 frame-%02d.jpg
Os quadros resultantes podem ser enviados repetindo o item de imagem no payload Python ou cURL. Se a referência atual da API para sua conta expor uma forma nativa de conteúdo de vídeo, siga essa referência e valide-a primeiro com um clipe pequeno. A listagem do modelo confirma a capacidade de vídeo; o formato de transporte deve ser verificado na documentação da API ativa para sua integração.
Function Calling com Contexto Visual
O function calling é útil quando o modelo deve transformar o que vê em uma ação da aplicação. Mantenha a ferramenta restrita e valide seus argumentos no código da aplicação.
tools = [
{
"type": "function",
"function": {
"name": "flag_document",
"description": "Envia um documento para verificação manual.",
"parameters": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Por que a revisão é necessária."},
"page_or_frame": {"type": "string", "description": "Página ou timestamp do vídeo."},
},
"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": "Sinalize este documento se campos-chave estiverem obscuros."},
],
}
],
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)
Trate os argumentos da ferramenta como saída não confiável do modelo. Valide o JSON, verifique permissões e execute a função fora do modelo. Uma observação visual não deve acionar diretamente uma ação irreversível sem as verificações que seu workflow exige.
Controles de Raciocínio
A API de chat completions compatível com OpenAI da Novita inclui os campos enable_thinking e separate_reasoning, e a listagem do Ling 3.0 Flash VL inclui suporte a raciocínio. Teste esses campos com uma requisição pequena antes de adicioná-los a um wrapper de produção:
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 as duas tendências e indique qual precisa de investigação."},
],
}
],
enable_thinking=True,
separate_reasoning=True,
max_tokens=512,
temperature=0.2,
)
print(response.choices[0].message)
A saída de raciocínio pode alterar a análise da resposta e a latência. Se sua aplicação precisa apenas de uma legenda ou chamada de ferramenta, deixe esses campos desligados e compare a qualidade com a requisição mais simples primeiro.
Lista de Verificação de Integração
Antes de ir além de um teste básico:
- Confirme o ID exato do modelo e o endpoint em vez de usar o nome de exibição.
- Teste uma URL de imagem pública, depois uma URL de dados base64 e valide a manipulação de imagens privadas separadamente.
- Mantenha
max_tokenslimitado e registre o uso e a latência sem reter conteúdo de imagem desnecessário. - Teste as configurações de detalhe da imagem em textos pequenos, gráficos e fotografias comuns.
- Valide os argumentos da ferramenta antes da execução e lide com uma resposta sem chamada de ferramenta.
- Para workflows de vídeo, defina a amostragem de quadros, o rastreamento de timestamps e o payload de vídeo nativo suportado pela referência da API ativa.
- Verifique novamente a disponibilidade do modelo, preços e limites antes da produção; os valores do catálogo podem mudar.
FAQ
Qual ID de modelo devo usar?
Use inclusionai/ling-3.0-flash-vl. Ling 3.0 Flash VL é o nome de exibição, não o valor da requisição.
Qual endpoint este guia usa?
Use https://api.novita.ai/openai como a URL base do SDK ou envie requisições cURL para https://api.novita.ai/openai/v1/chat/completions.
Como envio uma imagem?
Adicione um array content à mensagem do usuário com um item image_url e um item text. A URL da imagem pode apontar para uma imagem acessível ou usar uma URL de dados base64.
O modelo aceita vídeo?
A listagem do modelo da Novita verificada em 9 de setembro de 2026 lista vídeo como uma modalidade de entrada. O guia público de visão não documenta uma forma genérica de mensagem de vídeo direta, então confirme a referência da API ativa antes de enviar um payload de vídeo nativo. Um workflow de amostragem de quadros é a alternativa portátil.
Ele suporta function calling e raciocínio?
A listagem atual da Novita inclui ambos os recursos. Os exemplos acima mostram tools, enable_thinking e separate_reasoning; teste a forma da resposta e a latência com sua própria carga de trabalho.
