用模力方舟 API 完成首次大模型调用并接入自有应用

模力方舟是一个面向开发者、终端用户与产业场景的 AI 应用共创平台，核心能力包括高可用的模型 API 服务、API 工作流与模型微调服务。它把上百个开源大模型聚合到一套统一的接口之下，并提供 OpenAI 兼容的调用方式，因此已经写过 OpenAI SDK 代码的项目通常只需要替换 base URL 与令牌就能迁移过来。这篇教程面向第一次接触该平台、希望从零跑通一次模型调用并把能力接进自己程序的开发者，也适合想先在浏览器里试模型、再决定是否写代码的产品与运营同学。站内也提供了配套的 模力方舟 工具入口，可以先从那里进入工作台。

整篇内容按「注册登录 → 在线体验 → 创建令牌 → 发起 API 调用 → 完整示例 → 注意事项」的顺序展开，每一步都给出真实的地址、字段与代码，最后会用一个从头到尾能跑通的最小 Python 脚本收尾。

准备工作

在写第一行代码之前，需要先把账号与凭证准备好。模力方舟的登录体系与 Gitee 打通，所以准备工作主要围绕 Gitee 账号和访问令牌展开。

账号

• 访问模力方舟站点，点击右上角的「登录」按钮。
• 登录会引导你使用 Gitee 账号完成。如果还没有 Gitee 账号，需要先在 Gitee 注册一个，再回到模力方舟登录。
• 登录成功后系统会把你带到控制台，也就是后续管理工作台、令牌与资源的地方。

关于免费额度：每个账号每天可以免费调用各种模型，共 100 次。这个额度适合验证流程与做小规模试验，正式接入前建议先确认当前的计费与配额规则。

访问令牌

API 调用需要一枚访问令牌（access token），它在请求头里以 Bearer 形式携带。令牌在个人工作台的「访问令牌管理」中创建，创建后请立即妥善保存，不要写进公开仓库或前端代码里。文档中出现的示例令牌只是演示占位，不能直接使用，必须换成自己账号下生成的令牌。

运行环境

• Python 3 环境，并安装 requests 库，示例代码依赖它发起 HTTP 请求。
• 能访问外网的终端或 IDE，用于执行脚本。
• 如果使用其他语言，只要支持发送 HTTP POST 请求即可，接口本身与语言无关。

操作步骤

第一步：在模型广场在线体验模型

在写代码之前，先在浏览器里确认模型的行为，可以省掉很多调试时间。模型广场提供十几个类别、共一百多个模型的在线体验，无需编程。

1. 在页面顶部导航栏中找到并点击「模型广场」。
2. 广场中按类别陈列了各类模型，例如 DeepSeek、Qwen、Stable Diffusion 等。文本生成、图像生成等任务分属不同类别。
3. 选择一个感兴趣的文本生成模型，例如 DeepSeek-R1，点击进入模型体验页。
4. 详情页右侧会展示模型的基本介绍、接口信息与定价等信息。点击「在线体验」按钮，会打开一个对话界面。
5. 在输入框中输入问题或指令，例如「请帮我写一首关于春天的五言绝句」，然后点击发送。
6. 稍等片刻即可看到模型返回的内容。

这一步的价值不只是「玩一下」：模型详情页同时给出了该模型的接口示例代码片段，后面写脚本时可以直接以它为起点，避免把模型名称、路径写错。

第二步：创建并管理访问令牌

在线体验走的是平台自己的会话，不经过你的令牌；一旦要写代码调用，就必须有自己的令牌。

1. 进入个人工作台，找到「访问令牌管理」。
2. 新建一枚令牌，按用途命名，便于日后区分不同项目。
3. 复制生成的令牌字符串，保存在安全的位置。

令牌等同于账号在 API 层的身份，泄露即意味着他人可以消耗你的额度。不要把令牌硬编码进会提交到版本库的文件，也不要在客户端应用里直接分发。

第三步：理解接口地址与请求结构

模力方舟提供 OpenAI 兼容的接口，对话补全的地址是：

https://api.moark.com/v1/chat/completions

请求使用 POST，请求头需要两项：

• Authorization：值为 Bearer <your_access_token>，把尖括号部分换成你自己的令牌。
• Content-Type：值为 application/json。

请求体是一个 JSON 对象，常用字段如下：

字段	含义	示例
model	要调用的模型名称，需与模型广场中展示的名称一致	DeepSeek-R1
messages	对话消息数组，每条包含 role 与 content	[{"role": "user", "content": "..."}]
max_tokens	最大生成 token 数，控制回复长度上限	100
temperature	控制生成文本的随机性	0.7

响应结构与 OpenAI 的对话补全接口一致，正文内容位于 choices[0].message.content。HTTP 状态码为 200 表示成功，其他状态码需要读取响应体中的错误信息。

第四步：发起第一次 API 调用

把上面的要素拼起来，就是一个最小的调用脚本。注意把 <your_access_token> 替换成真实令牌：

import requests

url = "https://api.moark.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer <your_access_token>",
    "Content-Type": "application/json"
}
data = {
    "model": "DeepSeek-R1",
    "messages": [
        {"role": "user", "content": "请帮我写一首关于春天的五言绝句"}
    ],
    "max_tokens": 100,
    "temperature": 0.7
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    print("模型回应：", result["choices"][0]["message"]["content"])
else:
    print("请求失败，状态码：", response.status_code, "错误信息：", response.text)

运行后如果一切正常，终端会打印出模型生成的绝句。如果打印的是失败信息，先看状态码：401 类问题通常指向令牌无效或未正确拼接 Bearer 前缀，400 类问题通常指向请求体字段缺失或模型名称拼写错误。

第五步：把调用封装成可复用的函数

第一次跑通之后，把请求逻辑封装成函数，后续换模型、换提示词都只改参数。下面这个版本把地址与请求头提到模块级，函数只接收 payload：

import requests

API_URL = "https://api.moark.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer <your_access_token>",
    "Content-Type": "application/json",
}

def query(payload):
    print("Running Qwen2.5-72B-Instruct on Gitee AI!")
    response = requests.post(API_URL, headers=headers, json=payload)
    return response.json()

调用时传入不同的 model 与 messages 即可切换任务。例如把模型换成 Qwen2.5-72B-Instruct，提示词换成一道应用题：「小明数家里的鸡和兔，有头共 16 个，有脚共 44 只，请问小明家的鸡和兔分别有多少只？」模型会给出推理过程与答案。

一个完整示例

下面把前面几步串成一个完整可运行的脚本：读取环境变量中的令牌、构造请求、处理成功与失败两种分支，并把结果打印出来。这样写的好处是令牌不落在代码里，脚本可以直接放进版本库。

import os
import requests

API_URL = "https://api.moark.com/v1/chat/completions"
TOKEN = os.environ.get("MOARK_TOKEN")

if not TOKEN:
    raise SystemExit("请先设置环境变量 MOARK_TOKEN")

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

payload = {
    "model": "DeepSeek-R1",
    "messages": [
        {"role": "user", "content": "请帮我写一首关于春天的五言绝句"}
    ],
    "max_tokens": 100,
    "temperature": 0.7,
}

response = requests.post(API_URL, headers=headers, json=payload)

if response.status_code == 200:
    result = response.json()
    print(result["choices"][0]["message"]["content"])
else:
    print("请求失败，状态码：", response.status_code)
    print("错误信息：", response.text)

在终端里先导出令牌，再执行脚本：

export MOARK_TOKEN=你的访问令牌
python chat.py

预期输出是一段模型生成的五言绝句。到这里，从注册、在线体验、创建令牌到 API 调用的完整链路就走通了。接下来可以在这个脚本基础上做三件事：换模型对比效果、把 messages 改成多轮对话以保留上下文、把函数接入自己的服务端接口。

扩展场景：多轮对话

messages 是一个数组，天然支持多轮。把历史消息按顺序追加进去，模型就能看到上下文：

payload = {
    "model": "DeepSeek-R1",
    "messages": [
        {"role": "user", "content": "请帮我写一首关于春天的五言绝句"},
        {"role": "assistant", "content": "上一轮模型返回的内容"},
        {"role": "user", "content": "再写一首，主题换成秋天"}
    ],
    "max_tokens": 100,
    "temperature": 0.7,
}

注意上下文越长，消耗的 token 越多，max_tokens 只限制生成部分，不限制输入部分。

扩展场景：接入 Coding Agent 与桌面客户端

除了自己写代码，模力方舟的接口也可以配置进各类 AI 编程与对话工具。文档中列出了 Claude Code、Codex、Cursor、Trae、Qoder、OpenCode、Cline、RooCode、Continue、Cherry Studio、Chatbox、Dify、N8N 等工具的快速配置入口，以及 MCP 集成与 OAuth2 接入指南。这些工具的共同点是需要填写一个兼容 OpenAI 的 base URL 与一枚访问令牌，配置思路与上面的脚本一致：地址用 https://api.moark.com/v1 这一层，令牌用你在访问令牌管理中生成的那一枚。具体到每个工具的填写位置，以对应工具的配置页为准。

注意事项

• 免费额度有限：每个账号每天可免费调用各种模型共 100 次。调试阶段注意不要用循环反复请求，容易在不知不觉中耗尽当天额度。
• 令牌必须替换：文档与示例中出现的令牌字符串只是演示，直接复制会返回鉴权失败。请使用自己账号下生成的令牌。
• 模型名称要精确：model 字段需要与模型广场中展示的名称一致，大小写与连字符都不能随意改动，否则请求会被拒绝。
• 接口是 OpenAI 兼容的：请求体字段与响应结构沿用 OpenAI 对话补全的约定，正文在 choices[0].message.content。迁移已有代码时主要改地址与令牌。
• 错误处理要读响应体：非 200 状态码时，response.text 里通常带有具体原因，比只看状态码更容易定位问题。
• 价格、配额与可用模型会变化：模型广场中的定价信息、免费额度规则与在架模型列表都可能调整，接入生产前请以官网当前展示的信息为准。
• 不要把令牌写进前端：令牌具备消耗额度的能力，应保存在服务端或环境变量中，避免随客户端分发。

走完这篇的流程，你已经具备在模力方舟上调用任意在架文本模型的能力。下一步可以按需探索模型微调（支持 Qwen2.5、Qwen3、SDXL、Flux 等文本生成与文生图模型）、算力市场按需租用 GPU，以及把应用发布到 AI 应用市场。