Skip to content

NFL API 文档

生成符合规范的营养标签，管理食谱，并通过编程方式提取营养数据。目前，对于所有符合条件的账户，有两项功能可以正常运行： 实时标签嵌入 和 服务器渲染导出REST 资源 API 目前在商业计划中处于早期访问阶段。

该 API 只接受和返回 JSON（标签渲染端点返回二进制文件）。

定义

https://nutritionfactlabel.com/api/v1

API 端点

所有 REST 资源都使用同一个版本化的基本 URL。重大变更只会以新的版本号前缀发布。在抢先体验期间，您的欢迎邮件会确认用于您密钥的基本 URL。

资源 URL 模式概述

/v1/recipes
/v1/recipes/{RECIPE_ID}
/v1/recipes/{RECIPE_ID}/label.{svg|png|pdf}
/v1/ingredients
/v1/ingredients/{INGREDIENT_ID}
/v1/analyze

验证

使用您的私钥对每个请求进行身份验证 Authorization 头部。密钥的作用域限定在您的帐户范围内，并包含您套餐的权限：与应用程序相同的服务器端网关。

务必妥善保管钥匙。 切勿在客户端代码中发布密钥；请通过后端代理。泄露的密钥应立即通过技术支持进行轮换。

示例请求

curl https://nutritionfactlabel.com/api/v1/recipes \
  -H 'Authorization: Bearer nfl_live_9f30c2...'

速率限制

为了保持公平稳定： 每分钟 60 个请求 每个键；标签渲染额外限制为 5个并发请求的正文大小为 1 MB。超过限制后，您将获得 429 与一个 Retry-After 标题。

示例回复

HTTP/2 429 Too Many Requests
Retry-After: 22

{ "error": { "code": "rate_limited",
  "message": "Try again in 22 seconds." } }

实时标签嵌入 现已上市

在任何网站上显示始终更新的标签，无需 API 密钥。在生成器中的食谱中启用嵌入功能（食谱行 → 嵌入）获取其公共代币。

脚本标签会自动调整高度；更新 NFL 中的食谱，所有显示嵌入内容的页面都会更新。专业版和商业版套餐；禁用嵌入内容会立即删除令牌。

定义：脚本标签

<script src="https://nutritionfactlabel.com/embed.js"
        data-label="YOUR_EMBED_TOKEN"
        data-width="290"></script>

替代方案：iframe

<iframe
  src="https://nutritionfactlabel.com/embed/TOKEN"
  width="290" height="560" frameborder="0"
  title="Nutrition Facts"></iframe>

标签出口 现已上市

SVG/PNG/PDF 由与应用程序相同的引擎在服务器端渲染，并强制执行计划规则（格式、文件类型、水印）。在 API 密钥正式发布之前，您可以使用会话令牌直接调用它。返回二进制文件，或 403 超出你的计划。

关于与应用内导出功能一致的两点说明。应用在浏览器中渲染，因此如果您需要生成一个没有标签的标签，请使用此接口。 jpg 目前返回PNG字节，而 eps 和 ai 这些是仅供导出的格式，该端点不支持。

定义

POST /functions/v1/export-label
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "fileType": "pdf",
  "data": { ...label state },
  "extra": { }
}

食谱 提前体验 · 商业

核心对象：配料、份量和 label_format （涵盖 114 个国家/地区的 152 种格式）生成计算结果 label：营养成分按司法管辖区四舍五入，配料表，过敏原。

主要属性： id, name, servings, serving_weight_g, label_format, label （计算得出） embed_enabled时间戳。

定义

GET    /v1/recipes
POST   /v1/recipes
GET    /v1/recipes/{ID}
PUT    /v1/recipes/{ID}
DELETE /v1/recipes/{ID}
GET    /v1/recipes/{ID}/label.pdf

示例回复

{
  "id": "rcp_2m4k9q",
  "name": "Chocolate Chip Cookies",
  "servings": 12,
  "serving_weight_g": 28,
  "label_format": "standard",
  "label": {
    "calories": 140,
    "total_fat_g": 7,
    "allergens": ["wheat","milk","soy"],
    ...
  },
  "embed_enabled": false
}

原料 提前体验 · 商业

可自定义配料，包括每 100 克营养成分、过敏原种类和可选成本，与应用程序中创建的配料相同，可在生成器中搜索。美国农业部配料地址为： usda:{fdc_id}; 放 "archived": true 归档（默认情况下已从列表中排除）。

定义

GET    /v1/ingredients
POST   /v1/ingredients
GET    /v1/ingredients/{ID}
PUT    /v1/ingredients/{ID}
DELETE /v1/ingredients/{ID}

示例请求

POST /v1/ingredients

{
  "name": "Organic almond flour",
  "nutrients_per_100g": {
    "calories": 571, "total_fat_g": 50,
    "protein_g": 21, "dietary_fiber_g": 10
  },
  "allergens": ["tree_nuts"],
  "cost_per_unit": 12.5, "unit": "kg"
}

营养分析 提前体验 · 商业

无需保存配方即可进行一次性分析。返回相同结果。 label 对象加 claims：营养成分声明中所述数值符合要求（例如） “膳食纤维的良好来源”）及其 CFR 引用。未匹配的名称将与 USDA 进行匹配。

示例请求

POST /v1/analyze

{
  "label_format": "standard",
  "servings": 12,
  "serving_weight_g": 28,
  "ingredients": [
    { "ingredient_id": "usda:173410", "grams": 120 },
    { "name": "brown sugar", "grams": 80 }
  ]
}

错误

常规 HTTP 错误代码；错误体是 JSON 格式，包含稳定的机器代码和人类可读的错误信息。 400 输入格式错误 401 密钥错误 403 超出你的计划范围 404 未找到/不是您的 429 限价 500 使用退避策略重试。

示例回复

{
  "error": {
    "code": "plan_format_not_allowed",
    "message": "The 'eu-1169' label format
      requires the Professional plan."
  }
}

获取访问权限

嵌入功能无需密钥；可按食谱启用（专业版及以上）。REST API 提前访问权限包含在内。 商业 计划：电子邮件 support@nutritionfactlabel.com 您将通过电子邮件收到账户信息，密钥将在一个工作日内发放。

找不到您需要的接口？请告诉我们。早期合作伙伴将指导产品路线图的制定。

升级到商务版