API protocol

POST · Text chat

Direct answerPOST /v1/chat/completions. Authentication, parameters, examples in three languages, result validation and error handling.

Updated · Reviewed

OpenFox · Text chat

POST https://api.openfox.vip/v1/chat/completions

Model ID: YOUR_MODEL_ID

Authentication

Authorization: Bearer $OPENFOX_API_KEY

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

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

Request parameters

  • model (body, string, Required): 模型 ID
  • messages (body, array, Required): 对话消息列表
  • temperature (body, number, Optional): 采样温度
  • top_p (body, number, Optional): 核采样参数
  • n (body, integer, Optional): 生成数量
  • stream (body, boolean, Optional): 是否流式响应
  • stream_options (body, object, Optional): See schema details.
  • stop (body, provider-specific, Optional): 停止序列
  • max_tokens (body, integer, Optional): 最大生成 Token 数
  • max_completion_tokens (body, integer, Optional): 最大补全 Token 数
  • presence_penalty (body, number, Optional): See schema details.
  • frequency_penalty (body, number, Optional): See schema details.
  • logit_bias (body, object, Optional): See schema details.
  • user (body, string, Optional): See schema details.
  • tools (body, array, Optional): See schema details.
  • tool_choice (body, provider-specific, Optional): See schema details.
  • response_format (body, object, Optional): See schema details.
  • seed (body, integer, Optional): See schema details.
  • reasoning_effort (body, string, Optional): 推理强度 (用于支持推理的模型)
  • modalities (body, array, Optional): See schema details.
  • audio (body, object, 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

The example uses non-streaming text. Tool calls, images and sampling parameters depend on the selected model and channel.

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/chat/completions' \
  -H "Authorization: Bearer $OPENFOX_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hello!"}],"stream":false}' \
  --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 choices[].message.content. Tool-only replies need a separate tool loop. This example does not enable streaming.
# 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/chat/completions"
    headers = {}
    headers["Authorization"] = "Bearer " + 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\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello!\"}],\"stream\":false}"))

    text = '\n'.join(c.get('message', {}).get('content') or '' for c in data.get('choices', []))
    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/chat/completions");
const headers = {"Content-Type":"application/json"};
if (!process.env.OPENFOX_API_KEY) throw Error('Set OPENFOX_API_KEY');
headers["Authorization"] = "Bearer " + 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",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "stream": false
});

const text = data.choices?.map(c => c.message?.content).filter(x => typeof x === 'string').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 choices[].message.content. Tool-only replies need a separate tool loop. This example does not enable streaming.

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": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "model",
            "messages"
          ],
          "properties": {
            "model": {
              "type": "string",
              "description": "模型 ID",
              "example": "gpt-4"
            },
            "messages": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "role",
                  "content"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "enum": [
                      "system",
                      "user",
                      "assistant",
                      "tool",
                      "developer"
                    ],
                    "description": "消息角色"
                  },
                  "content": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": [
                                "text",
                                "image_url",
                                "input_audio",
                                "file",
                                "video_url"
                              ]
                            },
                            "text": {
                              "type": "string"
                            },
                            "image_url": {
                              "type": "object",
                              "properties": {
                                "url": {
                                  "type": "string",
                                  "description": "图片 URL 或 base64"
                                },
                                "detail": {
                                  "type": "string",
                                  "enum": [
                                    "low",
                                    "high",
                                    "auto"
                                  ]
                                }
                              }
                            },
                            "input_audio": {
                              "type": "object",
                              "properties": {
                                "data": {
                                  "type": "string",
                                  "description": "Base64 编码的音频数据"
                                },
                                "format": {
                                  "type": "string",
                                  "enum": [
                                    "wav",
                                    "mp3"
                                  ]
                                }
                              }
                            },
                            "file": {
                              "type": "object",
                              "properties": {
                                "filename": {
                                  "type": "string"
                                },
                                "file_data": {
                                  "type": "string"
                                },
                                "file_id": {
                                  "type": "string"
                                }
                              }
                            },
                            "video_url": {
                              "type": "object",
                              "properties": {
                                "url": {
                                  "type": "string"
                                }
                              }
                            }
                          }
                        }
                      }
                    ],
                    "description": "消息内容"
                  },
                  "name": {
                    "type": "string",
                    "description": "发送者名称"
                  },
                  "tool_calls": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "example": "function"
                        },
                        "function": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "arguments": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  },
                  "tool_call_id": {
                    "type": "string",
                    "description": "工具调用 ID(用于 tool 角色消息)"
                  },
                  "reasoning_content": {
                    "type": "string",
                    "description": "推理内容"
                  }
                }
              },
              "description": "对话消息列表"
            },
            "temperature": {
              "type": "number",
              "minimum": 0,
              "maximum": 2,
              "default": 1,
              "description": "采样温度"
            },
            "top_p": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "default": 1,
              "description": "核采样参数"
            },
            "n": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "description": "生成数量"
            },
            "stream": {
              "type": "boolean",
              "default": false,
              "description": "是否流式响应"
            },
            "stream_options": {
              "type": "object",
              "properties": {
                "include_usage": {
                  "type": "boolean"
                }
              }
            },
            "stop": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ],
              "description": "停止序列"
            },
            "max_tokens": {
              "type": "integer",
              "description": "最大生成 Token 数"
            },
            "max_completion_tokens": {
              "type": "integer",
              "description": "最大补全 Token 数"
            },
            "presence_penalty": {
              "type": "number",
              "minimum": -2,
              "maximum": 2,
              "default": 0
            },
            "frequency_penalty": {
              "type": "number",
              "minimum": -2,
              "maximum": 2,
              "default": 0
            },
            "logit_bias": {
              "type": "object",
              "additionalProperties": {
                "type": "number"
              },
              "properties": {}
            },
            "user": {
              "type": "string"
            },
            "tools": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "example": "function"
                  },
                  "function": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "parameters": {
                        "type": "object",
                        "description": "JSON Schema 格式的参数定义",
                        "properties": {}
                      }
                    }
                  }
                }
              }
            },
            "tool_choice": {
              "oneOf": [
                {
                  "type": "string",
                  "enum": [
                    "none",
                    "auto",
                    "required"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "function": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              ]
            },
            "response_format": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "text",
                    "json_object",
                    "json_schema"
                  ]
                },
                "json_schema": {
                  "type": "object",
                  "description": "JSON Schema 定义",
                  "properties": {}
                }
              }
            },
            "seed": {
              "type": "integer"
            },
            "reasoning_effort": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ],
              "description": "推理强度 (用于支持推理的模型)"
            },
            "modalities": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "text",
                  "audio"
                ]
              }
            },
            "audio": {
              "type": "object",
              "properties": {
                "voice": {
                  "type": "string"
                },
                "format": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "required": true
  }
}

Sources and verification

docs/openapi/relay.json · relaykit/dto/openai_request.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.

Use cases

  • getting-started
  • troubleshooting

API protocols

  • /v1/chat/completions

FAQ

Does this guarantee model availability?

No. Check the exact model, group and endpoint permissions in the marketplace.

Do examples include live credentials?

No. Set environment variables on your server and replace YOUR_MODEL_ID with an available exact model ID.

Should I retry immediately after a timeout?

Do not automatically retry creation requests. Check the request ID, task status and usage to avoid duplicate charges.

Official sources

  1. OpenFox API Official