DOCUMENTATION

接入 Atria API

支持 Chat Completions、Messages 和 Responses 三种标准接口,可直接接入现有应用与 Agent 工具。

鉴权:创建 API Key

Atria API 使用你在控制台创建的 API Key 识别调用者。创建过程只需几步。

  1. 1
    登录控制台使用 Google 账号登录,然后进入 API Key 页面。
  2. 2
    填写密钥名称使用能区分环境或应用的名称,例如 production-agent。
  3. 3
    创建并立即复制点击“创建密钥”后复制完整 Key。完整内容只显示一次,关闭提示后无法再次查看。
  4. 4
    安全保存将 Key 放入服务端环境变量或密码管理器,不要写入前端代码。
如果 Key 丢失,请吊销旧 Key 并创建新的 Key;系统无法恢复已经隐藏的完整 Key。前往 API Key 控制台 →

鉴权与环境变量

所有请求都使用 Bearer API Key。Key 只在创建时完整显示一次,请保存到密码管理器或服务端环境变量。

macOS / Linux

export ATRIA_API_KEY=atr_xxx

Windows PowerShell

$env:ATRIA_API_KEY="atr_xxx"

请求头

Authorization: Bearer <ATRIA_API_KEY>
Content-Type: application/json

非流式调用

适合一次性获取完整回答。复制下面的命令,替换 API Key 后即可运行。

curl -X POST https://api.atria-asi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn",
    "messages": [{"role": "user", "content": "hi"}]
  }'

流式调用

适合聊天界面,模型生成的内容会持续返回。curl 会直接逐行显示结果。

curl -N -X POST https://api.atria-asi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": true
  }'

Messages 接口

兼容 Anthropic Messages API,使用 x-api-key 鉴权。适合已有 Anthropic SDK 或工具链。

curl -X POST https://api.atria-asi.ai/v1/messages \
  -H "x-api-key: $ATRIA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "hi"}]
  }'

Responses 接口

兼容 OpenAI Responses API,使用 input 字段提交文本或结构化输入。

curl -X POST https://api.atria-asi.ai/v1/responses \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn",
    "input": "hi"
  }'

理解返回结果

三种接口的字段结构不同。下面列出最常用的正文路径、结束原因和 token 用量位置,接入时无需遍历整个 JSON。

Chat Completions回答正文: choices[0].message.content结束原因: choices[0].finish_reasonToken 用量: usage.prompt_tokens / completion_tokens流式增量: choices[0].delta.content
Messages回答正文: content[0].text结束原因: stop_reasonToken 用量: usage.input_tokens / output_tokens流式增量: content_block_delta.delta.text
Responses回答正文: output[0].content[0].text结束原因: statusToken 用量: usage.input_tokens / output_tokens流式增量: response.output_text.delta

流式增量

流式响应使用 SSE。逐行读取 data: 事件并拼接增量文本;收到 [DONE] 或对应 completed/stop 事件后结束。不要把每个事件当作一条完整回答。

data: {"choices":[{"delta":{"content":"Hello"}}]}

data: {"choices":[{"delta":{"content":" world!"}}]}

data: [DONE]

Token 用量

usage 用于控制台统计和成本观测。输入与输出 token 会在流结束后结算,因此流式请求进行中看到的用量可能暂未更新。

模型概览与接口选择

Atria Dawn 面向科研分析、代码开发与多轮 Agent 任务。当前提供 Atria-Dawn 一个模型,根据应用使用的 SDK 或请求格式选择接口即可。

可用模型

请求中的 model 字段固定使用 Atria-Dawn,名称区分大小写。点击下方 ID 可查看完整调用示例。

Model ID上下文窗口
Atria-Dawn →512K tokens

Atria-Dawn 支持下述三种接口,以及非流式和流式调用。模型 ID 在三种接口中保持一致。

组织适合任务的输入

  1. 01
    科研与资料分析提供研究问题、相关文献片段和分析范围,并明确需要的结论形式,例如证据对照、研究假设或实验方案。需要引用时,将来源信息一并传入。
  2. 02
    代码与工程任务提供相关代码、报错信息、运行环境和验收条件,让模型围绕具体问题生成实现或修改建议;再用测试结果继续迭代。
  3. 03
    多轮 Agent 工作流提供任务目标、可用工具和当前状态。由应用或 Agent 执行工具调用,并将结果作为后续输入交回模型,逐步推进任务。

选择调用接口

已有项目沿用当前 SDK 对应的接口即可;通过 HTTP 直接接入时,可从 Chat Completions 示例开始。切换接口时,请同时调整输入字段和响应解析方式。

接口与路径输入字段输出上限参数
Chat Completions/v1/chat/completionsmessagesmax_completion_tokens或 max_tokens
Messages/v1/messagesmessagesmax_tokens
Responses/v1/responsesinputmax_output_tokens

理解 512K 上下文与输出长度

512K 表示一次请求可容纳的上下文规模,包含输入内容与生成内容。系统提示、历史对话、文档片段和工具结果都会占用输入空间;组织长上下文时,需要为回答预留空间。

上下文窗口不等于单次回答长度。上表的输出上限参数以 token 为单位,接受 1–65,536 的整数,用于限制本次生成长度;实际输出还取决于停止条件和剩余上下文。它不是目标字数,也不会保证生成到该长度。

处理长文档或多轮任务时,优先保留相关材料和必要历史,明确要求的输出格式,并根据任务设置输出上限。三个推理接口不再设置应用层请求体大小上限,但仍需满足模型上下文、可用额度及接入链路的限制。

开始调用与验证结果

复制下方示例,使用控制台创建的 API Key 完成一次简短请求。接入 Messages 或 Responses 时,保持 model 字段为 Atria-Dawn,并使用对应的请求路径、鉴权头和输入字段。

将模型接入正式任务前,用有代表性的输入检查结果正确性、指令遵循、响应时间和 token 用量。调整提示词、工具配置或接口后,复测这些任务。

Atria-Dawn

下面是此模型的 Chat Completions 最小请求。先设置 ATRIA_API_KEY 环境变量,再复制运行;把 hi 替换成你的问题即可开始使用。

curl -X POST https://api.atria-asi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ATRIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Atria-Dawn",
    "messages": [{"role": "user", "content": "hi"}]
  }'

使用 Messages 或 Responses 时,沿用此模型 ID,并按对应示例调整请求体。

接入 Agent 工具

只要 Agent 支持 OpenAI 或 Anthropic 兼容的自定义模型,就可以填入 Atria API 地址、API Key 和 model ID 接入。下面给出常用工具的最小配置。

接入前准备

先在控制台创建 API Key,并将其保存为 ATRIA_API_KEY 环境变量。所有示例均使用模型 ID Atria-Dawn,请保持大小写一致。

export ATRIA_API_KEY=atr_xxx

Claude Code

Claude Code 通过 Messages 接口连接 Atria。Host 不要带 /v1,Claude Code 会自动请求 /v1/messages。

export ANTHROPIC_BASE_URL=https://api.atria-asi.ai
export ANTHROPIC_AUTH_TOKEN=$ATRIA_API_KEY
claude --model Atria-Dawn

限制 Read 工具读取图片和 PDF

Atria-Dawn 接收纯文本输入。可通过 PreToolUse Hook,在 Claude Code 的 Read 工具读取图片或 PDF 前拒绝该操作;先将所需内容提取成文本,再交给模型。以下步骤需要本机已安装 Python 3。

1. 保存拦截脚本

将以下完整脚本保存为 block_pdf_image_read.py,记下实际绝对路径,例如 /absolute/path/block_pdf_image_read.py。示例路径只是占位符,请替换为你本机的路径。

#!/usr/bin/env python3
"""
PreToolUse hook: block the Read tool from reading PDF and image files.
"""
import json
import sys


IMAGE_EXTENSIONS = (
    ".apng",
    ".avif",
    ".bmp",
    ".gif",
    ".heic",
    ".heif",
    ".ico",
    ".jfif",
    ".jpeg",
    ".jpg",
    ".jxl",
    ".png",
    ".svg",
    ".tif",
    ".tiff",
    ".webp",
)


def main():
    hook_input = json.loads(sys.stdin.read())
    file_path = hook_input.get("tool_input", {}).get("file_path", "")

    if file_path.lower().endswith(".pdf"):
        reason = "Reading PDF files with the Read tool is not allowed."
    elif file_path.lower().endswith(IMAGE_EXTENSIONS):
        reason = "Reading image files with the Read tool is not allowed."
    else:
        sys.exit(0)

    output = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": reason,
        }
    }
    print(json.dumps(output, ensure_ascii=False))

    sys.exit(0)


if __name__ == "__main__":
    main()

2. 合并 Hook 配置

在 ~/.claude/settings.json 中合并以下 hooks 配置。已有 PreToolUse 时追加该条规则,不要覆盖其他设置或 Hook。若使用 CLAUDE_CONFIG_DIR 自定义配置目录,则修改该目录中的 settings.json。command 中填写脚本的绝对路径,并保留路径两侧的引号。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"/absolute/path/block_pdf_image_read.py\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. 验证拦截范围

在新的 Claude Code 会话中,分别让 Read 工具读取 .txt、.pdf 和 .png 文件:文本应正常读取,PDF 和图片应收到拒绝原因。若未拦截,请检查 Python 3、脚本路径及 Hook 执行错误。

这不是全局附件过滤器:脚本仅按扩展名拦截 Read,不覆盖直接粘贴、上传、@文件、Bash 或 MCP 输入;执行失败或超时也不保证阻止读取。不要向此模型发送图片或 PDF 原文件,请粘贴提取后的文字。

Claude Code Hook 配置说明 ↗

Codex

在 ~/.codex/config.toml 中添加自定义 provider。Codex 使用 Responses 接口。

配置纯文本模型

Atria-Dawn 仅接收文本。客户端若按多模态模型处理图片参数 -i/--image 或粘贴的截图,请求可能被拒绝并返回 400 Atria-Dawn is not a multimodal model。通过自定义模型目录声明 input_modalities,可让支持该配置的 Codex 按纯文本模型处理输入。

以下模型目录示例面向 Codex CLI 0.154.0 及以上版本。先运行 codex --version 检查版本;不同版本的目录字段和工具开关可能不同,请按所用版本核对。先在终端中设置 ATRIA_API_KEY,再启动 Codex。

1. 创建模型目录文件

将以下 JSON 保存为 ~/.codex/atria-catalog.json。保留完整字段;如果启动时出现 missing field <name>,检查是否遗漏字段,以及客户端版本是否匹配。

{
  "models": [
    {
      "slug": "Atria-Dawn",
      "display_name": "Atria-Dawn",
      "base_instructions": "You are a coding agent running in the Codex CLI. You collaborate with the user in a shared workspace to accomplish their software engineering goals.\n\nYou can only receive text input. Images, screenshots, PDFs, and other binary attachments are not available to you. If the user refers to an attachment you cannot see, say so plainly and ask them to paste the relevant text instead.",
      "supported_reasoning_levels": [
        {
          "effort": "low",
          "description": "Fast responses with lighter reasoning"
        },
        {
          "effort": "medium",
          "description": "Balances speed and reasoning depth"
        },
        {
          "effort": "high",
          "description": "Greater reasoning depth for complex problems"
        }
      ],
      "shell_type": "unified_exec",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "support_verbosity": false,
      "truncation_policy": {
        "mode": "tokens",
        "limit": 10000
      },
      "experimental_supported_tools": [],
      "context_window": 512000,
      "max_context_window": 512000,
      "input_modalities": [
        "text"
      ]
    }
  ]
}

input_modalities: ["text"] 用于声明文本输入能力。context_window 和 max_context_window 均设为 512000,供客户端估算上下文预算与自动压缩时机;不要填写超出模型实际能力的数值。base_instructions 还要求模型在无法查看附件时明确告知用户,并请求相关文本。

2. 在用户配置中加载目录

将下面的配置合并到 ~/.codex/config.toml。model、model_provider 和 model_catalog_json 位于文件顶层,须放在 [model_providers.atria] 等表声明之前。已有同名字段或表时修改原值,不要重复追加。

model = "Atria-Dawn"
model_provider = "atria"
model_catalog_json = "~/.codex/atria-catalog.json"

[model_providers.atria]
name = "Atria"
base_url = "https://api.atria-asi.ai/v1"
env_key = "ATRIA_API_KEY"
wire_api = "responses"
自定义 model_catalog_json 会替换模型目录,而不是合并。若通过 -m 或修改 model 切换模型,也要把对应模型加入这个文件;缺少元数据时可能出现 Model metadata for <slug> not found,并回退到默认能力,不能继续依赖当前模型的纯文本声明。

3. 可选:关闭看图工具

当前官方配置使用 tools.view_image。可以在同一 config.toml 的 [tools] 表中加入以下配置,避免模型调用本地看图工具。较早的配置示例写作 [features] view_image = false;请以安装版本的配置参考为准,不要将两种写法当作通用开关。关闭工具不等于图片转文本。

[tools]
view_image = false

Codex 官方配置参考 ↗

4. 重启并验证

保存后重启 Codex,使用 Atria-Dawn 发送一个纯文本任务。确认没有目录解析错误或模型元数据缺失警告。处理图片、截图或 PDF 时,先在客户端外完成 OCR 或文本提取,再粘贴文字;不要依赖模型读取二进制附件。

codex --model Atria-Dawn

WorkBuddy

在设置中选择自定义模型,然后填入:

Provider: Custom / OpenAI CompatibleBase URL: https://api.atria-asi.ai/v1API Key: atr_xxxModel: Atria-DawnAPI: Chat Completions

保存后选中 Atria-Dawn,发送一条简短任务验证连接。

Qoder

在设置中选择自定义模型,然后填入:

Provider: Custom → OpenAI CompatibleAPI: Responses APIBase URL: https://api.atria-asi.ai/v1API Key: atr_xxxModel ID: Atria-Dawn

保存后选中 Atria-Dawn,发送一条简短任务验证连接。

OpenClaw

在 OpenClaw 配置中注册自定义 provider,并将默认模型指向 atria/Atria-Dawn。

{
  agents: { defaults: { model: { primary: "atria/Atria-Dawn" } } },
  models: { providers: { atria: {
    baseUrl: "https://api.atria-asi.ai/v1",
    apiKey: "${ATRIA_API_KEY}",
    api: "openai-responses",
    models: [{ id: "Atria-Dawn", name: "Atria Dawn" }]
  } } }
}

Hermes

运行 hermes model,选择 Custom endpoint,然后填入:

Base URL: https://api.atria-asi.ai/v1API Key: atr_xxxModel: Atria-DawnFormat: OpenAI

保存后选中 Atria-Dawn,发送一条简短任务验证连接。

速率限制

每个账户每分钟可发送的请求总数存在上限,账户下的所有 API Key 共享这一额度,Chat Completions、Messages 和 Responses 三个接口也共享同一计数。超过上限时返回 429,响应头包含:

Retry-After: 42        # 建议等待的秒数x-rpm-limit: 60        # 每分钟请求上限x-rpm-remaining: 0     # 本分钟剩余次数

Retry-After 表示建议等待的秒数,x-rpm-limit 是每分钟请求上限,x-rpm-remaining 是本分钟剩余可用次数。成功响应同样带有这两个字段,可用于客户端自适应限速。限额按固定分钟窗口重置;请求失败时会退还本分钟的计数。

常见状态码

401API Key 无效或已吊销
429请求频率过高或额度不足
5xx服务暂时不可用,请稍后重试