When do you need DashScope's native API instead of its OpenAI-compatible endpoint?

## Two doors to the same models Alibaba Cloud Model Studio serves Qwen through two request surfaces on the same hosts: - **native DashScope**, under `/api/v1/services/...` — for text generation, the path is `/api/v1/services/aigc/text-generation/generation` - **OpenAI-compatible**, under `/compatible-mode/v1` — Chat Completions request and response shape They are not two products. They are two envelopes around overlapping capability, and choosing between them is a portability-versus-capability decision you should be able to argue explicitly. ## The native request shape The native body is structured differently from Chat Completions. Rather than a flat object with `model`, `messages` and generation parameters as siblings, it nests: `model` at the top, the conversation inside **`input`**, and the generation settings inside **`parameters`**. Vendor flags that ride in `extra_body` in compatible mode are ordinary members of `parameters` here. Alibaba's own `dashscope` Python SDK targets this surface — `Generation.call(model=..., messages=..., result_format="message", ...)` — and reads the key from `DASHSCOPE_API_KEY` automatically, which is one small ergonomic win over the OpenAI client. That SDK also carries the region setting as module state: assigning `dashscope.base_http_api_url` to the Singapore native base URL switches deployments, because the default targets the Beijing host. ## The streaming difference people get wrong In compatible mode, streaming behaves as OpenAI users expect: every chunk is a **delta**, and you concatenate them. On the native surface, streaming events by default carry the **full text generated so far**, not just the increment — you set **`incremental_output=True`** to get delta semantics. Get this wrong and the symptom is unmistakable: output that repeats itself with exponentially growing duplication, because you concatenated cumulative snapshots. It is a five-minute bug once you have seen it and a bewildering one the first time. A related native knob is **`result_format`**, which selects whether the response is returned in a plain text-completion shape or a message shape with roles; message shape is what you want for chat and is the modern default. ## What actually forces you to native Be honest about this list, because "native is more powerful" is a vague claim that does not survive a follow-up question. The real drivers: 1. **Asynchronous task submission.** Some generation work — long-running media generation in particular — is submitted as a task and polled for completion rather than answered inline. A Chat Completions body has no place to express that lifecycle, so it lives on the native surface, driven by DashScope-specific request headers and a task-status endpoint. 2. **Endpoints that are not chat-shaped.** Model Studio hosts services beyond conversational text generation. Anything whose request or response does not fit a `messages` array plus a completion has no compatible-mode representation. 3. **Native-only parameters.** `incremental_output` and `result_format` are the clearest examples: they describe the native envelope itself and have no analogue in the OpenAI shape. Everything else — ordinary chat, streaming chat, tool calling, JSON output, the thinking flag — is reachable from compatible mode, with vendor parameters passed through `extra_body`. ## What you give up by going native Portability, and more of it than teams expect. The compatible surface is the reason a Qwen swap is a base-URL change: LLM frameworks, observability proxies, gateway products and internal abstractions overwhelmingly speak Chat Completions. Write directly against `input`/`parameters` and every one of those integrations needs a bespoke adapter, and a future provider migration becomes a rewrite of the call layer rather than a config change. You also give up a shared mental model. On a team where most services speak the OpenAI shape, the one service using the native envelope is the one nobody wants to touch. ## The recommendation to give in an interview Default to compatible mode. Use native for the specific capability that has no compatible-mode expression, and when you do, **put it behind your own interface** — a function that takes your domain types and returns your domain types, with the native body construction entirely inside it. Then the blast radius of the vendor-specific envelope is one file, and the rest of the codebase keeps its portability. A useful tie-breaker when both surfaces can do the job: pick the one your operational tooling already understands. If your token accounting, tracing and rate-limit middleware are built around Chat Completions responses, a native call is invisible to all of it until you write the adapter — and unmeasured traffic is a worse problem than a slightly less ergonomic request body.