API 协议

POST · Claude Messages

直接答案POST /v1/messages。包含鉴权、请求参数、三种语言示例、结果判定与错误处理。

更新 · 审核信息

OpenFox · Claude Messages

POST https://api.openfox.vip/v1/messages

Model ID: YOUR_MODEL_ID

Authentication

x-api-key: $OPENFOX_API_KEY

Create a model API key in API Keys. Dashboard sessions and personal access tokens are not model API credentials.

anthropic-version: 2023-06-01

Keep credentials in environment variables on your server. Do not paste real keys, cookies or account records into this guide.

Request parameters

  • anthropic-version (header, string, Required): Anthropic API 版本
  • x-api-key (header, string, Optional): Anthropic API Key (可选,也可使用 Bearer Token)
  • model (body, string, Required): See schema details.
  • messages (body, array, Required): See schema details.
  • system (body, provider-specific, Optional): See schema details.
  • cache_control (body, object, Optional): See schema details.
  • inference_geo (body, string, Optional): See schema details.
  • max_tokens (body, integer, Required): See schema details.
  • temperature (body, number, Optional): See schema details.
  • top_p (body, number, Optional): See schema details.
  • top_k (body, integer, Optional): See schema details.
  • stream (body, boolean, Optional): See schema details.
  • stop_sequences (body, array, Optional): See schema details.
  • tools (body, array, Optional): See schema details.
  • tool_choice (body, provider-specific, Optional): See schema details.
  • thinking (body, object, Optional): See schema details.
  • context_management (body, object, Optional): See schema details.
  • output_config (body, object, Optional): See schema details.
  • output_format (body, object, Optional): See schema details.
  • container (body, provider-specific, Optional): See schema details.
  • mcp_servers (body, array, Optional): See schema details.
  • metadata (body, object, Optional): See schema details.
  • speed (body, string, Optional): See schema details.
  • service_tier (body, string, Optional): See schema details.

Example values are not server defaults. Model-specific parameter support must be confirmed for the selected channel.

Model and channel limitations

max_tokens=1024 is an example, not a server default or a limit shared by all models.

Request example

Run one language example only. Creation requests may be charged; do not run every example or retry automatically.

Set OPENFOX_REQUEST_ID from the original X-Request-Id when recovering images. Set OPENFOX_TASK_ID from a real task creation response when querying tasks.

curl

# Bash / WSL; curl 7.76+ and jq. Run ONE language example, not all of them.
umask 077
RESULT=$(mktemp)
trap 'rm -f "$RESULT"' EXIT
: "${OPENFOX_API_KEY:?Set OPENFOX_API_KEY}"
curl --silent --show-error --fail-with-body --max-time 180 'https://api.openfox.vip/v1/messages' \
  -H "x-api-key: $OPENFOX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  --data-raw '{"model":"YOUR_MODEL_ID","max_tokens":1024,"messages":[{"role":"user","content":"Hello!"}]}' \
  --output "$RESULT" || exit 1
jq -e 'type == "object" and (.error | not) and (.success != false) and (.code != false)' "$RESULT" >/dev/null || exit 1
# HTTP/business envelope checked only. Complete result validation is required:
# Require non-empty text blocks in content[]. Tool-use blocks need a separate tool loop.
# Use the Python or JavaScript example in this guide for result processing.

python

# Python 3.10+; install: pip install httpx
import asyncio, json, os
from urllib.parse import quote, urlparse
import httpx

async def main():
    url = "https://api.openfox.vip/v1/messages"
    headers = {"anthropic-version":"2023-06-01"}
    headers["x-api-key"] = "" + os.environ["OPENFOX_API_KEY"]
    params = {}
    async with httpx.AsyncClient(timeout=30, follow_redirects=False) as client:
        async def read(target, method='GET', payload=None):
            response = await client.request(method, target, headers=headers, params=params, json=payload)
            response.raise_for_status()
            value = response.json()
            if not isinstance(value, dict) or value.get('error') or value.get('success') is False or value.get('code') is False:
                raise RuntimeError('API business error')
            return value
        data = await read(url, "POST", json.loads("{\"model\":\"YOUR_MODEL_ID\",\"max_tokens\":1024,\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}]}"))

    text = '\n'.join(c.get('text', '') for c in data.get('content', []) if c.get('type') == 'text')
    if not text.strip():
        raise RuntimeError('No completed text output')
    print(text)

async def bounded():
    await asyncio.wait_for(main(), timeout=180)

asyncio.run(bounded())

javascript

// Node.js 20+; save as example.mjs and run: node example.mjs
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 180000);
const signal = controller.signal;
try {
const url = new URL("https://api.openfox.vip/v1/messages");
const headers = {"anthropic-version":"2023-06-01","Content-Type":"application/json"};
if (!process.env.OPENFOX_API_KEY) throw Error('Set OPENFOX_API_KEY');
headers["x-api-key"] = "" + process.env.OPENFOX_API_KEY;
const read = async (target, method = 'GET', payload) => {
  const response = await fetch(target, { method, headers, signal, redirect: 'error', body: payload === undefined ? undefined : JSON.stringify(payload) });
  if (!response.ok) throw Error('HTTP ' + response.status);
  const data = await response.json();
  if (!data || typeof data !== 'object' || data.error || data.success === false || data.code === false) throw Error('API business error');
  return data;
};
let data = await read(url, "POST", {
  "model": "YOUR_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
});

const text = data.content?.filter(x => x.type === 'text').map(x => x.text).join('\n');
if (typeof text !== 'string' || !text.trim()) throw Error('No completed text output');
console.log(text);
} finally { clearTimeout(timer); }

Results and success criteria

Require non-empty text blocks in content[]. Tool-use blocks need a separate tool loop.

Error handling

Check both HTTP status and business errors. A timeout does not prove the operation failed. Do not automatically retry creation requests; inspect the original request or usage first.

401/403: check credentials, scopes, model permissions and IP rules. 429: check quota and rate limits. 5xx: preserve a non-secret request ID and contact support.

Python and JavaScript share a 180-second network deadline. Read-only polling is bounded. Unknown or failure states stop the flow. Image decoding is local CPU work with byte and pixel limits.

Only the image editing example uploads a local file. Set OPENFOX_IMAGE_PATH to a supported image. Other examples do not upload files. Download external results without platform credentials. Task artifacts require format-specific verification.

Full request schema

{
  "parameters": [
    {
      "name": "anthropic-version",
      "in": "header",
      "description": "Anthropic API 版本",
      "required": true,
      "example": "",
      "schema": {
        "type": "string",
        "example": "2023-06-01"
      }
    },
    {
      "name": "x-api-key",
      "in": "header",
      "description": "Anthropic API Key (可选,也可使用 Bearer Token)",
      "required": false,
      "example": "",
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "model",
            "messages",
            "max_tokens"
          ],
          "properties": {
            "model": {
              "type": "string",
              "example": "claude-3-opus-20240229"
            },
            "messages": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "role",
                  "content"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "user",
                      "assistant"
                    ]
                  },
                  "content": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "text",
                                "image",
                                "tool_use",
                                "tool_result"
                              ]
                            },
                            "text": {
                              "type": "string"
                            },
                            "source": {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": [
                                    "base64",
                                    "url"
                                  ]
                                },
                                "media_type": {
                                  "type": "string"
                                },
                                "data": {
                                  "type": "string"
                                },
                                "url": {
                                  "type": "string"
                                }
                              }
                            },
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "input": {
                              "type": "object",
                              "properties": {}
                            },
                            "tool_use_id": {
                              "type": "string"
                            },
                            "content": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    ]
                  }
                }
              }
            },
            "system": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {}
                  }
                }
              ]
            },
            "cache_control": {
              "type": "object",
              "properties": {}
            },
            "inference_geo": {
              "type": "string"
            },
            "max_tokens": {
              "type": "integer",
              "minimum": 1
            },
            "temperature": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "top_p": {
              "type": "number"
            },
            "top_k": {
              "type": "integer"
            },
            "stream": {
              "type": "boolean"
            },
            "stop_sequences": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "tools": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "input_schema": {
                    "type": "object",
                    "properties": {}
                  }
                }
              }
            },
            "tool_choice": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "auto",
                        "any",
                        "tool",
                        "none"
                      ]
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                }
              ]
            },
            "thinking": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "enabled",
                    "disabled"
                  ]
                },
                "budget_tokens": {
                  "type": "integer"
                }
              }
            },
            "context_management": {
              "type": "object",
              "properties": {}
            },
            "output_config": {
              "type": "object",
              "properties": {}
            },
            "output_format": {
              "type": "object",
              "properties": {}
            },
            "container": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "object",
                  "properties": {}
                }
              ]
            },
            "mcp_servers": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {}
              }
            },
            "metadata": {
              "type": "object",
              "properties": {
                "user_id": {
                  "type": "string"
                }
              }
            },
            "speed": {
              "type": "string",
              "enum": [
                "standard",
                "fast"
              ]
            },
            "service_tier": {
              "type": "string",
              "enum": [
                "auto",
                "standard_only"
              ]
            }
          }
        },
        "examples": {}
      }
    }
  }
}

Sources and verification

docs/openapi/relay.json · relaykit/dto/claude.go · 2026-11-03

SHA-256: aeee6c35a35b2eaced964401f3826f369ad7ac8985c17989dcbbe08337d9fa01

source-reviewed; upstream-not-tested; legacy-schema-needs-field-review

Source review is not upstream business verification. Availability and billing depend on your account, group and channel.

适用场景

  • getting-started
  • troubleshooting

API 协议

  • /v1/messages

常见问题

这里是否保证模型可调用?

不保证。请在模型广场核对精确型号、账号分组与端点权限。

示例是否使用真实密钥?

不使用。请在自己的服务端设置环境变量,并将 YOUR_MODEL_ID 替换为可用的精确模型 ID。

接口超时可以立即重试吗?

创建请求不应自动重试。先核对请求编号、任务状态和用量,避免重复收费。

官方来源

  1. OpenFox API 官方