Developer Docs

开发者文档

神农 API 提供 OpenAI 兼容的 HTTP 接口。使用 API Key 即可在任意语言或框架中调用农业 Agent 大模型与内置工具。

免费注册创建 API Key在线体验快速开始 ↓

概述

对外开放的程序化接口以 POST /api/v1/chat/completions 为主，请求与响应格式与 OpenAI Chat Completions API 兼容，并扩展了 tool_results 字段用于调试工具调用。

01
注册并充值

在控制台创建账户，充值后即可按量调用（¥1 ≈ 25 万 tokens）。

02
创建 API Key

在「API Keys」页面生成 sk-nong-... 密钥，仅创建时完整展示。

03
发起请求

使用 Bearer 鉴权调用 Chat Completions，可直接对接 OpenAI SDK。

项目说明
Base URL生产环境请使用你的部署域名，例如 https://api.shennong.ai。本地开发为 http://localhost:3000。
协议HTTPS（生产）/ HTTP（本地）
Content-Typeapplication/json
默认模型sn（可通过请求体 model 覆盖）

获取 API Key

  1. 注册 或 登录 神农控制台。
  2. 进入 API Keys，点击「创建密钥」并命名（如「生产环境」）。
  3. 复制完整密钥（格式 sk-nong-xxxxxxxx），关闭弹窗后无法再次查看。
  4. 将密钥存入环境变量，勿提交到代码仓库。
密钥支持启用/停用与删除。停用或删除后，使用该密钥的请求将返回 401。可在控制台查看各密钥的调用次数与最近使用时间。

鉴权

服务端集成请使用 API Key。在控制台「API Keys」页面创建密钥后，在请求头中携带：

HTTP Header
Authorization: Bearer sk-nong-xxxxxxxx
API Key 仅在创建时完整展示一次，请妥善保存。禁用或删除密钥后，对应请求将返回 401。 Playground 页面使用浏览器 Session Cookie 鉴权，不适合服务端调用。

快速开始

最简文本对话（非流式）：

cURL
curl -X POST "https://api.shennong.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-nong-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sn",
    "stream": false,
    "messages": [
      { "role": "user", "content": "介绍一下水稻常见病虫害" }
    ]
  }'

SDK 接入

神农 API 与 OpenAI SDK 兼容。将 base_url 指向你的部署地址 + /api/v1 即可，无需修改业务代码。

Python（openai）

pip install openai
pip install openai
Python
from openai import OpenAI

client = OpenAI(
    api_key="sk-nong-YOUR_KEY",
    base_url="https://api.shennong.ai/api/v1",
)

resp = client.chat.completions.create(
    model="sn",
    messages=[{"role": "user", "content": "玉米叶片发黄可能是什么原因？"}],
)
print(resp.choices[0].message.content)

Node.js / TypeScript（openai）

npm install openai
npm install openai
TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SHENNONG_API_KEY,
  baseURL: "https://api.shennong.ai/api/v1",
});

const resp = await client.chat.completions.create({
  model: "sn",
  messages: [{ role: "user", content: "介绍一下水稻常见病虫害" }],
});

console.log(resp.choices[0]?.message?.content);

流式（OpenAI SDK）

Python 流式
stream = client.chat.completions.create(
    model="sn",
    stream=True,
    messages=[{"role": "user", "content": "写一首关于春耕的短诗"}],
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

原生 fetch

JavaScript
const res = await fetch("https://api.shennong.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-nong-YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "sn",
    stream: false,
    messages: [{ role: "user", content: "你好" }],
  }),
});
const data = await res.json();
console.log(data.choices[0].message.content);

Chat Completions

POST/api/v1/chat/completions

创建一次对话补全，支持流式与非流式，可按需启用平台工具。

请求体

字段类型说明
messages二选一arrayOpenAI 风格消息数组，支持多模态 image_url。
ui_messages二选一arrayAI SDK UI 消息格式，供 Playground 等前端场景使用。
model可选string模型 ID，默认 sn。
stream可选booleantrue 返回 SSE 流（chat.completion.chunk）；false 或省略返回单个 JSON 对象。默认非流式。
temperature可选number采样温度，传给上游模型。
enabled_tools可选string[]启用的工具 ID 列表，例如 ["vet_list_species", "vet_classify_disease"]。 不传则不挂载工具。
tools可选arrayOpenAI 风格工具声明，服务端会提取 function.name 作为工具 ID。

非流式响应

200 OK
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1718000000,
  "model": "sn",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 128,
    "total_tokens": 170
  },
  "tool_results": [
    {
      "tool_call_id": "...",
      "name": "vet_classify_disease",
      "input": { "species_id": "cow", "file_id": "..." },
      "output": { "success": true, "predicted_chinese": "..." }
    }
  ]
}

tool_results 为平台扩展字段，汇总本次请求中工具执行的输入与输出，便于调试与审计。

消息格式

messages 遵循 OpenAI Chat Completions 约定。每条消息包含 role（user / assistant）与 content。平台会自动注入系统提示，客户端无需传入system 消息。

messages 示例
{
  "messages": [
    { "role": "user", "content": "玉米叶片发黄可能是什么原因？" },
    { "role": "assistant", "content": "可能原因包括缺氮、涝害……" },
    { "role": "user", "content": "如果近期降雨偏多呢？" }
  ]
}

多模态图片

用户消息可使用 OpenAI 多模态格式。服务端会自动将图片 ingest 到平台对象存储，供兽医推理等工具使用。

  • 公网 URL：image_url.url 为可访问的 http/https 图片地址（单张最大 20 MB）。
  • Base64 Data URL：data:image/jpeg;base64,... 同样支持。
多模态 messages
{
  "enabled_tools": ["vet_classify_disease"],
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "请分析这张牛的照片可能是什么病" },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/cattle.jpg"
          }
        }
      ]
    }
  ]
}
图片 ingest 后会在服务端生成 file_id。调用 vet_classify_disease 时，若用户消息中仅有一张图片，模型可省略file_id 参数；多张图片时需显式传入对应 file_id。

工具调用

通过 enabled_tools 声明本次请求允许模型调用的工具。模型会在对话中自主决定是否触发工具；工具执行结果会计入用量并出现在tool_results 中。

hello_world

Hello World — 打印一句 Hello World 问候语

vet_list_species

畜禽种类查询 — 查询兽医疾病推理支持的畜禽种类

vet_classify_disease

兽医疾病推理 — 根据用户上传的畜禽照片推理可能的疾病

兽医疾病推理参数

vet_classify_disease 接受 species_id（cow / pig / sheep / chicken）与可选的 file_id。可先调用 vet_list_species 获取支持的畜禽种类列表。

启用工具
{
  "model": "sn",
  "stream": false,
  "enabled_tools": ["vet_list_species", "vet_classify_disease"],
  "messages": [
    { "role": "user", "content": "帮我查一下支持哪些畜禽，并分析我上传的猪照片" }
  ]
}

流式响应

设置 "stream": true 后，响应为 Server-Sent Events（SSE），Content-Type 为 text/event-stream。每个事件行为 data: {...}，流结束时发送 data: [DONE]。

流式请求
curl -N -X POST "https://api.shennong.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer sk-nong-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sn",
    "stream": true,
    "messages": [{ "role": "user", "content": "写一首关于春耕的短诗" }]
  }'
SSE 帧示例
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1718000000,"model":"sn","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1718000000,"model":"sn","choices":[{"index":0,"delta":{"content":"风"},"finish_reason":null}]}

data: [DONE]

流式模式下，token 用量在流结束后按实际生成内容计费。

错误码

错误响应体通常为 { "error": { "message", "type", "code"? } }。

HTTPtype / code说明
401authentication_error未登录或 API Key 无效。
402insufficient_balance账户余额不足，请先在控制台充值。
400invalid_request_error请求体无效、缺少 messages、图片格式错误等。
502upstream_error上游模型服务异常（仅非流式）。

计费说明

  • 按 token 计费：¥1 = 25 万 tokens（输入 + 输出合计）。
  • 每次调用前会校验账户余额；余额 ≤ 0 时返回 402。
  • 在控制台可查看用量明细、充值（支付宝）与管理 API Key。

对象存储上传（控制台「文件」页）目前仅支持 Session 登录，暂无独立 HTTP API Key 接口。多模态接入推荐在messages 中直接传入公网图片 URL 或 Base64。