Compatibilidade OpenAI

Migre do OpenAI alterando três parâmetros: base_url, api_key e model.

QwenCloud fornece APIs compatíveis com OpenAI. Se você tiver código existente usando o SDK OpenAI ou API REST, mude alterando três parâmetros: base_url, api_keye model.

Migração rápida

Python

```python
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
  model="qwen3.7-plus",
  messages=[{"role": "user", "content": "Hello!"}],
)
print(completion.choices[0].message.content)
```

Node.js

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});

async function main() {
  const completion = await openai.chat.completions.create({
    model: "qwen3.7-plus",
    messages: [{ role: "user", content: "Hello!" }],
  });
  console.log(completion.choices[0].message.content);
}

main();
```

curl

```bash
curl https://maas.qwencloudapi.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.7-plus",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

Antes de começar, obtenha uma chave de API e defini-lo como uma variável de ambiente. Se você usa o OpenAI SDK, instale-o.

APIs suportadas

Conclusões de bate-papo

A API de conclusões de bate-papo (/v1/chat/completions) é amplamente compatível com API de bate-papo da OpenAI. As principais diferenças estão listadas abaixo.

Qwen-specific parâmetros

Esses parâmetros não fazem parte do padrão OpenAI. No OpenAI Python SDK, passe-os via extra_body.

Diferenças comportamentais

• response_format suporta json_object apenas (não json_schema).
• tool_choice suporta auto, nonee objeto de função específico ({"type": "function", "function": {"name": "..."}}). O required o valor não é suportado.
• tools suporta function digite apenas.
• parallel_tool_calls o padrão é false (O padrão do OpenAI é true).
• n suporta 1-4 e está limitado a modelos específicos (qwen-plus, qwen-plus-character).
• web_search_options não é suportado. Usar extra_body.enable_search e extra_body.search_options em vez disso.

Parâmetros não suportados

Os seguintes parâmetros são ignorados silenciosamente: frequency_penalty, logit_bias, max_completion_tokens, metadata, prediction, prompt_cache_key, reasoning_effort, service_tier, store, verbosity.

Para obter a referência completa da API e exemplos de código, consulte Conclusões do bate-papo.

API de respostas

A API Responses usa o mesmo base_url como conclusões de bate-papo: https://maas.qwencloudapi.com/compatible-mode/v1.

Em comparação com as conclusões do chat, a API Responses oferece:

• Ferramentas integradas: web_search, code_interpreter, web_extractore image_search -- nenhuma configuração de ferramenta externa é necessária.
• Multi-turno simplificado: Passe previous_response_id em vez de construir um histórico completo de mensagens.
• Integração de conversas: emparelhe com a API Conversations para gerenciamento automático de contexto.
• Cache de sessão: armazena automaticamente o contexto em cache entre os turnos para reduzir a latência e o custo. Habilite com o x-dashscope-session-cache: enable cabeçalho. Consulte Cache de sessão.

Migrar das conclusões do bate-papo

Para mudar das conclusões do chat para a API Responses:

1. Mantenha base_url inalterado e altere o caminho do terminal de /v1/chat/completions para /v1/responses.
2. Leia a resposta com output_text em vez de choices[0].message.content.
3. Para conversas com vários turnos, passe previous_response_id em vez de anexar mensagens manualmente.

Para obter referência completa e exemplos de código, consulte Respostas.

Incorporação

A API de incorporação (/v1/embeddings) é compatível com API de incorporação da OpenAI. Principais diferenças:

• encoding_format: Apenas float é suportado (opção padrão e única).
• user: Não suportado.
• dimensions: Os valores disponíveis dependem do modelo. Por exemplo, text-embedding-v4 suporta 2.048, 1.536, 1.024 (padrão), 768, 512, 256, 128 e 64.

Para modelos suportados e exemplos de código, consulte Incorporação.

API de arquivo

A API de arquivo (/v1/files) é compatível com API de arquivos da OpenAI, com estas diferenças:

• **purpose**deve ser file-extract (para análise de documentos com Qwen-Long/Qwen-Doc) ou batch (para processamento em lote). Valores OpenAI como fine-tune e assistants não são suportados.
• Recuperação de conteúdo de arquivo (GET /v1/files/{file_id}/content) não é compatível.
• Filtragem de lista: o purpose e order parâmetros ativados GET /v1/files não são suportados.
• Limites de armazenamento: 10.000 arquivos, 100 GB no total. Os arquivos nunca expiram.

Para a referência completa, consulte Arquivo.

API em lote

A API de lote (/v1/batches) é compatível com API Batch da OpenAI, com estas diferenças:

• Desconto de 50% no custo em comparação com preços em tempo real.
• completion_window: Suporta 24h a 336h (14 dias). Aceita unidades "h" (horas) e "d" (dias) com valores inteiros. OpenAI é fixado em 24h.
• Metadados extras: metadata.ds_name (nome da tarefa) e metadata.ds_description (descrição da tarefa).
• Filtros de lista extras: ds_name, input_file_ids, status, create_after, create_before.
• Limites de arquivo de entrada: até 50.000 solicitações por arquivo, 500 MB no total, 6 MB por linha. Todas as solicitações em um arquivo devem usar o mesmo modelo.

Para obter o guia completo do fluxo de trabalho, consulte API Batch.

API de conversas

A API Conversations é uma Qwen-specific recurso sem equivalente direto do OpenAI. Ele gerencia automaticamente o contexto multiturno entre dispositivos e sessões. Ele usa o mesmo base_url como a API de respostas: https://maas.qwencloudapi.com/compatible-mode/v1.

Use-o com a API Responses para injetar contexto histórico sem sincronização manual de mensagens.

Para a referência completa, consulte Conversas.