# ZipFlow Docs (/en)
Welcome to the ZipFlow documentation. ZipFlow is a model API service: one
account and one Base URL (`https://api.zipflow.xyz/v1`) that accepts multiple
API formats — OpenAI, Anthropic, Google Gemini, DeepSeek, and more —
across chat, embeddings, rerank, image, audio, music, and video.
Get an API key from the [ZipFlow console](https://zipflow.xyz), then start calling:
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{"model": "gpt-4.1", "messages": [{"role": "user", "content": "Hello!"}]}'
```
## Browse the docs [#browse-the-docs]
* [Chat Completions](/en/api/openai-chat)
* [Anthropic Messages](/en/api/anthropic-chat)
* [Google Gemini](/en/api/google-gemini-chat)
* [Image](/en/api/openai-image)
* [Video](/en/api/openai-video)
* [Realtime](/en/api/openai-realtime)
* [Models List](/en/api/v1-models)
* [App Integrations](/en/apps/cherry-studio)
# Privacy Policy (/en/privacy)
**Last updated: August 17, 2026**
ZipFlow ("we", "us", or "our") provides a model API service that lets you access a variety of AI models through a single interface (the "Service"), together with the website at [https://zipflow.xyz](https://zipflow.xyz) and its related documentation (the "Site"). This Privacy Policy explains how we collect, use, share, and protect information about you when you use the Site and Service.
By using the Site or Service, you agree to the practices described in this Privacy Policy. If you do not agree, please do not use the Site or Service.
## 1. Information We Collect [#1-information-we-collect]
### Information you provide to us [#information-you-provide-to-us]
* **Account information**: when you register, we collect details such as your username, email address, and password (passwords are stored in hashed form).
* **Communications**: if you contact us (for example, for support), we collect the content of your messages and your contact details.
* **Billing and payment information**: when you top up your balance or make purchases, we process transaction details such as amounts, payment method, and billing records. Payment processing may be handled by third-party payment providers.
### Information collected automatically [#information-collected-automatically]
When you visit the Site or use the Service, we may automatically collect:
* **Usage and log data**: IP address, browser type and version, operating system, referring pages, pages viewed, and timestamps.
* **Service data**: API request metadata such as the model used, request and response token counts, latency, timestamps, and cost, which we use for billing, usage analytics, and abuse prevention.
* **Cookies and similar technologies**: we use cookies and similar technologies to keep you signed in, remember your preferences, and understand how the Site is used. See "Cookies and Tracking Technologies" below for more details.
### Content you submit through the Service [#content-you-submit-through-the-service]
When you use the API, you submit content ("Inputs") to ZipFlow, and ZipFlow's models generate responses ("Outputs") in return.
**Our commitment to your content:** ZipFlow does not read, monitor, or sell your Inputs or Outputs, and does not use them to train models. We process your content only to deliver the Service — to generate the response, measure usage, and prevent abuse or fraud — or where required by law.
## 2. How We Use Your Information [#2-how-we-use-your-information]
We use the information we collect to:
* Provide, operate, and maintain the Service;
* Generate responses to your requests;
* Process transactions and manage your account and balance;
* Measure and report usage, tokens, and costs;
* Detect, prevent, and address fraud, abuse, security incidents, and technical issues;
* Communicate with you about your account, service updates, and support requests;
* Comply with legal obligations and enforce our terms; and
* Improve and develop the Site and Service.
## 3. How We Share Your Information [#3-how-we-share-your-information]
We do not sell your personal information. We may share information in the following circumstances:
* **Service providers**: with vendors who perform services on our behalf (such as hosting, payment processing, and analytics), under confidentiality obligations.
* **Legal and safety**: where required by law, regulation, legal process, or governmental request, or where necessary to protect the rights, property, or safety of ZipFlow, our users, or the public.
* **Business transfers**: in connection with a merger, acquisition, reorganization, or sale of assets.
* **With your consent**: for any other purpose you authorize.
We may also share aggregated or de-identified information that cannot reasonably be used to identify you.
## 4. Data Retention [#4-data-retention]
We retain personal information only for as long as necessary to provide the Service, meet legal and regulatory obligations, resolve disputes, and enforce our agreements.
* **Request logs (metadata)**: details such as the model used, token counts, latency, cost, and timestamps are retained for up to 30 days for billing, usage analytics, and abuse prevention.
* **Content (Inputs and Outputs)**: we do not persist your prompt or response content longer than necessary to deliver the response, and we do not retain it for our own purposes.
When information is no longer needed, we delete or anonymize it in accordance with applicable law.
## 5. Data Security [#5-data-security]
We use reasonable technical and organizational measures designed to protect your information from unauthorized access, loss, misuse, or alteration. However, no method of transmission over the internet or electronic storage is completely secure, and we cannot guarantee absolute security. You are responsible for keeping your account credentials and API keys confidential.
## 6. Cookies and Tracking Technologies [#6-cookies-and-tracking-technologies]
We use cookies and similar technologies to remember your preferences, keep you signed in, and analyze how the Site is used. You can control cookies through your browser settings; disabling cookies may affect the functionality of the Site.
## 7. Third-Party Services and Links [#7-third-party-services-and-links]
The Site and Service may contain links to, or rely on, third-party websites and services (including payment processors). We are not responsible for the privacy practices of these third parties. This Privacy Policy applies only to information collected by ZipFlow. We encourage you to review the privacy policies of any third-party services you interact with.
## 8. International Data Transfers [#8-international-data-transfers]
ZipFlow operates globally, and your information may be transferred to and processed in countries other than the one where you live. Where required by applicable law, we implement appropriate safeguards for such transfers.
## 9. Your Rights and Choices [#9-your-rights-and-choices]
Depending on where you live, you may have rights regarding your personal information, such as the right to access, correct, delete, or restrict the processing of your information, and the right to object to certain processing. To exercise these rights, contact us at the address below. You may also update your account information through the console, and you can opt out of marketing communications by following the unsubscribe instructions in those messages.
## 10. Children's Privacy [#10-childrens-privacy]
The Site and Service are not directed to children under 13, and we do not knowingly collect personal information from children under 13. If you believe a child has provided us with personal information, please contact us so we can delete it.
## 11. Changes to This Privacy Policy [#11-changes-to-this-privacy-policy]
We may update this Privacy Policy from time to time. When we do, we will revise the "Last updated" date at the top of this page. We encourage you to review this page periodically. Your continued use of the Site or Service after changes are posted constitutes acceptance of the revised policy.
## 12. Contact Us [#12-contact-us]
If you have questions or concerns about this Privacy Policy or our privacy practices, please contact us at [support@zipflow.xyz](mailto:support@zipflow.xyz).
# Cherry Studio - Desktop AI Client (/en/apps/cherry-studio)
In the ZipFlow Console under System Settings -> Chat settings, you can add the following quick option to enable one-click fill to Cherry Studio from the API Keys page:
```json
{ "Cherry Studio": "cherrystudio://providers/api-keys?v=1&data={cherryConfig}" }
```
🍒 Cherry Studio is a powerful desktop AI client designed for professional users, integrating 30+ industry-specific AI assistants to meet various work scenario requirements and significantly improve work efficiency.
* Official Website: [https://cherry-ai.com/](https://cherry-ai.com/)
* Download: [https://cherry-ai.com/download](https://cherry-ai.com/download)
* Documentation: [https://docs.cherry-ai.com](https://docs.cherry-ai.com)
## ZipFlow Integration Method [#zipflow-integration-method]
### Parameter Configuration [#parameter-configuration]
Provider Type: Any type supported by ZipFlow\
API Key: Obtain from ZipFlow\
API Host: ZipFlow site address
### Step-by-Step Guide [#step-by-step-guide]
1. Copy API key from ZipFlow
2. Add Provider
3. Add Models
4. Return to Chat Page
5. Switch to ZipFlow Model
## Drawing in Cherry Studio [#drawing-in-cherry-studio]
*First, you need to configure an API provider that supports drawing*
1. First, add models that support drawing
2. Drawing
# Claude Code (/en/apps/claude-code)
***
Unleash Claude’s raw power directly in your terminal. Search million-line codebases instantly. Turn hours-long workflows into a single command. Your tools. Your workflow. Your codebase, evolving at thought speed.
直接在你的终端中，释放 Claude 的强大威力。瞬间搜索百万行代码库。将数小时的工作流化为一条命令。你的工具。你的工作流。你的代码库，以思维速度进化。
1. Official Homepage: [https://www.anthropic.com/claude-code](https://www.anthropic.com/claude-code)
2. Installation Method: See the tutorial below on this page
## Demonstration [#demonstration]
***
### Features [#features]
| **Function Category** | **Feature** |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Code Understanding** | - Deep codebase analysis, utilizing intelligent agents to search and understand project structure and dependencies |
| | - Automatically generate high-level code overviews, quickly helping users understand the codebase |
| **Code Editing** | - Supports multi-file collaborative editing, suitable for complex code modifications |
| | - Provides practical and usable code suggestions that conform to project patterns and architecture |
| **Integration Capabilities** | - Supports direct execution in the terminal without context switching |
| | - Seamless integration with VS Code and JetBrains IDEs, eliminating the need for copy-pasting |
| **Code Generation and Optimization** | - Automatically generate code, create tests, fix errors, supporting the complete workflow from concept to commit |
| | - Optimized for code generation and understanding, incorporating advanced models like Claude Opus 4 |
| **Security and Flexibility** | - Changes require explicit user authorization, making file and command operations safer |
| | - Adapts to user code standards and supports custom configuration |
| **Toolchain Integration** | - Supports integration with tools like GitHub and GitLab to achieve automated workflows |
| | - Integrates with testing suites and build systems, enhancing existing development tools |
| **Cross-Platform and Extensibility** | - Supports Windows, macOS, and Linux operating systems |
| | - Configurable to run in SDKs or GitHub Actions, flexibly adapting to different requirements |
| **Primary Use Cases** | - Codebase onboarding and understanding, rapid ramp-up for new members |
| | - Code issue fixing and optimization workflow, from problem analysis to PR submission |
| | - Project code refactoring and new feature implementation |
| **User Feedback Highlights** | - Improves daily development efficiency, saving time spent on routine tasks |
| | - Excellent performance in handling complex multi-step tasks, expanding development possibilities |
## AI Model Configuration Method [#ai-model-configuration-method]
### Windows Graphical Guide [#windows-graphical-guide]
#### 1. Install Node.js Environment [#1-install-nodejs-environment]
Claude Code requires the Node.js environment to run.
* Open your browser and visit [https://nodejs.org/](https://nodejs.org/)
* Click to download the "LTS" version (Long-Term Support version recommended)
* After the download is complete, double-click the .msi file
* Follow the installation wizard to complete the installation, keeping the default settings
* It is recommended to use PowerShell instead of CMD
* If you encounter permission issues, try running as administrator
* Some antivirus software may flag it incorrectly; you might need to add it to a whitelist
After installation is complete, open PowerShell or CMD and enter the following commands:
```
node --version
npm --version
```
If the version number is displayed, the installation was successful
#### 2. Install Git Bash [#2-install-git-bash]
In the Windows environment, Git Bash is required to install Claude Code. After installation, environment variable setup and using Claude Code should still be done in standard PowerShell or CMD.
* Visit [https://git-scm.com/downloads/win](https://git-scm.com/downloads/win)
* Click "Download for Windows" to download the installer
* Run the downloaded .exe installation file
* Keep the default settings during the installation process and click "Next" to complete the installation
After installation is complete, open Git Bash and enter the following command to verify:
```
git --version
```
If the version number is displayed, the installation was successful
#### 3. Install Claude Code [#3-install-claude-code]
Open PowerShell and run the following command:
```
npm install -g @anthropic-ai/claude-code
```
This command downloads and installs the latest version of Claude Code from the official npm repository.
```
[Environment]::SetEnvironmentVariable('Path', ([Environment]::GetEnvironmentVariable('Path','User') + ";$HOME\.local\bin"), 'User')
```
After installation is complete, enter the following command to check if the installation was successful:
```
claude --version
```
If the version number is displayed, congratulations! Claude Code has been successfully installed.
#### 4. Set Environment Variables [#4-set-environment-variables]
To allow Claude Code to connect to your service, you need to set multiple environment variables:
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.ps1')
```
#### 5. Start Using Claude Code [#5-start-using-claude-code]
You can now start using Claude Code!
Open PowerShell and launch Claude Code directly:
```
# 启动 Claude Code
claude
```
To use in a specific project:
```
# 进入你的项目目录
cd C:\path\to\your\project
```
```
# 启动 Claude Code
claude
```
Enter the command:
```
/model
```
Press Enter to select the model; usually, the default settings are sufficient.
> Note: After setting and modifying environment variables, all models used (including official preset models) will call the custom access point and will not consume official account Quota.
### macOS Graphical Guide [#macos-graphical-guide]
#### 1. Install Claude Code CLI [#1-install-claude-code-cli]
Open Terminal
Open Terminal and run the following command:
```
curl -fsSL https://claude.ai/install.sh | bash
```
Optional: Run the provided command if prompted
```
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```
#### 2. Set Environment Variables [#2-set-environment-variables]
To allow Claude Code to connect to a third-party service, you need to set environment variables:
Enter the command:
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.sh | bash
```
After installation is complete, enter the following command to check if the installation was successful:
```
claude --version
```
If the version number is displayed, congratulations! Claude Code has been successfully installed.
#### 3. Start Using Claude Code [#3-start-using-claude-code]
You can now start using Claude Code!
Launch Claude Code directly:
```
# 启动 Claude Code
claude
```
To use in a specific project:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Claude Code
claude
```
Enter the command:
```
/model
```
Press Enter to select the official model; usually, the default model is sufficient
> Note: After setting and modifying the environment variable `ANTHROPIC_BASE_URL`, all models used (including official preset models) will call the custom access point and will not consume official account Quota.
#### 6. macOS Common Issues Resolution [#6-macos-common-issues-resolution]
??? example "macOS Security Settings Block Execution"
If the system prevents Claude Code from running:
* Open "System Preferences" → "Security & Privacy"
* Click "Open Anyway" or "Allow"
* Or run in `Terminal`: `sudo spctl --master-disable`
### Linux Graphical Guide [#linux-graphical-guide]
#### 1. Install Claude Code [#1-install-claude-code]
Open Terminal and run the following command:
```
curl -fsSL https://claude.ai/install.sh | bash
```
If you encounter permission issues, you can use sudo:
```
sudo curl -fsSL https://claude.ai/install.sh | bash
```
After installation is complete, enter the following command to check if the installation was successful:
```
claude --version
```
If the version number is displayed, congratulations! Claude Code has been successfully installed.
#### 2. Set Environment Variables [#2-set-environment-variables-1]
To allow Claude Code to connect to your service, you need to set two environment variables:
Enter the command:
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.sh | bash
```
#### 4. Start Using Claude Code [#4-start-using-claude-code]
You can now start using Claude Code!
Launch Claude Code directly:
```
# 启动 Claude Code
claude
```
To use in a specific project:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Claude Code
claude
```
Enter the command:
```
/model
```
Press Enter to select the official model; usually, the default model is sufficient
> Note: After setting and modifying the environment variable `ANTHROPIC_BASE_URL`, all models used (including official preset models) will call the custom access point and will not consume official account Quota.
#### 5. Linux Common Issues Resolution [#5-linux-common-issues-resolution]
??? example "Missing Dependency Libraries"
Some Linux distributions require the installation of additional dependencies:
```
# Ubuntu/Debian
sudo apt install build-essential
```
```
# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```
??? example "Environment Variables Not Taking Effect"
Check the following points:
* Confirm that the correct configuration file (`.bashrc` or `.zshrc`) was modified
* Restart the terminal or run `source ~/.bashrc`
* Verify settings: `echo $ANTHROPIC_BASE_URL`
# OpenAI Codex CLI (/en/apps/codex-cli)
***
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
1. Official Homepage: [https://chatgpt.com/codex](https://chatgpt.com/codex)
2. Project Homepage: [https://github.com/openai/codex](https://github.com/openai/codex)
3. Installation Method: See the tutorial below on this page
## Demonstration [#demonstration]
***
### Features [#features]
| **Function Category** | **Feature** |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Terminal-Based Coding Assistant | Codex CLI is a terminal-based interactive coding assistant used for editing code, generating patches, and running commands in the command line. |
| Tool-Driven Architecture | Provides tools such as `apply_patch`, `shell`, `update_plan`, and `multi_tool_use` for controlled modifications to repository files and operations. |
| Atomic Patch Editing | Uses a specialized patch format to atomically add/update/delete files via `apply_patch`, facilitating auditing and rollback. |
| Sandboxing and Approval | Supports sandboxing policies (e.g., `workspace-write`, `read-only`) and approval modes (`on-request`, `on-failure`, `never`) to control write and network access permissions. |
| Plan Tracking | `update_plan` is used to list steps and track status, requiring only one `in_progress` step at all times to maintain clear progress. |
| Interaction Guidelines | Sends brief introductory explanations before important operations, maintaining a friendly, concise tone and providing progress updates. |
| Security Constraints | Adheres to strict rules (no arbitrary changes to unrelated files, no adding copyright headers, no executing destructive commands), requiring user approval for sensitive operations. |
| Testing and Formatting | Recommended to run relevant tests and formatting tools after modification, but not responsible for fixing issues unrelated to the current task. |
| Output and Style | Final output adheres to CLI rendering specifications (e.g., `**` headings, backticks for paths/commands), maintaining a scannable and concise structure. |
| Parallel Execution | Supports running multiple tools in parallel via `multi_tool_use.parallel` to improve efficiency. |
## AI Model Configuration Method [#ai-model-configuration-method]
### Windows Graphical Guide [#windows-graphical-guide]
#### 1. Open Terminal [#1-open-terminal]
#### 2. Install WSL [#2-install-wsl]
For optimal performance on Windows, please install and use the Windows Subsystem for Linux (WSL2).
```
wsl --install
```
Restart the Windows computer after installation
* It is recommended to use PowerShell instead of CMD
* If you encounter permission issues, try running as administrator
* Some antivirus software may flag this as a false positive; you may need to add it to a whitelist
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```
Open a new PowerShell window in the tab bar and start WSL
```
wsl
```
Install Node.js
The version number is time-sensitive; please install the corresponding version according to the OpenAI official website requirements: [https://developers.openai.com/codex/windows](https://developers.openai.com/codex/windows)
```
nvm install 22
```
#### 3. Install Codex CLI [#3-install-codex-cli]
```
npm i -g @openai/codex
```
This command downloads and installs the latest version of Codex CLI from the official npm repository.
#### 4. Modify Configuration File [#4-modify-configuration-file]
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.ps1')
```
#### 5. Start Using Codex CLI [#5-start-using-codex-cli]
You can now start using Codex CLI!
Start WSL2
```
wsl
```
Launch Codex CLI directly:
```
codex
```
Use in a specific project:
```
cd mnt/c/path/to/your/project
```
```
codex
```
Press Enter to launch Codex CLI
> Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files
```
/model
```
> Note: After modifying the interface address, all models (including official preset models) will call the custom access point and will not use the official account quota.
### macOS Graphical Guide [#macos-graphical-guide]
#### 1. Install Homebrew (Skip if already installed) [#1-install-homebrew-skip-if-already-installed]
Homebrew is the package manager for macOS that installs missing software.
Official Website: [https://brew.sh](https://brew.sh)
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
#### 2. Install Node.js Environment [#2-install-nodejs-environment]
Update Homebrew
```
brew update
```
Install Node.js
```
brew install node
```
* If you encounter permission issues, you may need to use `sudo`
* The first run may require permission in System Preferences
* It is recommended to use `Terminal` or `iTerm2`
After installation, open the terminal and enter the following commands:
```
node --version
npm --version
```
If the version number is displayed, the installation was successful
#### 3. Install Codex CLI [#3-install-codex-cli-1]
Open the terminal and run the following command:
```
# Install Codex CLI globally
npm install -g @openai/codex
```
If you encounter permission issues, you can use sudo:
```
sudo npm install -g @openai/codex
```
After installation, enter the following command to check if the installation was successful:
```
codex --version
```
If the version number is displayed, congratulations! Codex CLI has been successfully installed.
#### 4. Modify Configuration File [#4-modify-configuration-file-1]
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```
#### 5. Start Using Codex CLI [#5-start-using-codex-cli-1]
You can now start using Codex CLI!
Launch Codex CLI directly:
```
codex
```
Use in a specific project:
```
cd mnt/c/path/to/your/project
```
```
codex
```
Press Enter to launch Codex CLI
> Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files
> Note: After modifying the interface address, all models (including official preset models) will call the custom access point and will not use the official account quota.
#### 6. macOS Common Issues Resolution [#6-macos-common-issues-resolution]
??? example "Permission Error During Installation"
Try the following solutions:
* Install using `sudo`: `sudo npm install -g @openai/codex`
* Or configure `npm` to use the user directory: `npm config set prefix ~/.npm-global`
??? example "macOS Security Settings Block Execution"
If the system blocks Codex CLI from running:
* Open "System Preferences" → "Security & Privacy"
* Click "Open Anyway" or "Allow"
* Or run in `Terminal`: `sudo spctl --master-disable`
### Linux Graphical Guide [#linux-graphical-guide]
#### 1. Install Node.js Environment [#1-install-nodejs-environment]
Codex CLI requires the Node.js environment to run.
Add NodeSource repository
```
sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
```
Install Node.js
```
sudo apt-get install -y nodejs
```
* Some distributions may require installing additional dependencies
* Use sudo if you encounter permission issues
* Ensure your user has write permissions in the npm global directory
After installation, open the terminal and enter the following commands:
```
node --version
npm --version
```
If the version number is displayed, the installation was successful
#### 2. Install Codex CLI [#2-install-codex-cli]
Open the terminal and run the following command:
```
# Install Codex CLI globally
npm install -g @openai/codex
```
If you encounter permission issues, you can use sudo:
```
sudo npm install -g @openai/codex
```
After installation, enter the following command to check if the installation was successful:
```
codex --version
```
If the version number is displayed, congratulations! Codex CLI has been successfully installed.
#### 3. Modify Configuration File [#3-modify-configuration-file]
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```
#### 4. Start Using Codex CLI [#4-start-using-codex-cli]
You can now start using Codex CLI!
Launch Codex CLI directly:
```
# Launch Codex CLI
codex
```
Use in a specific project:
```
# Navigate to your project directory
cd /path/to/your/project
```
```
# Launch Codex CLI
codex
```
Press Enter to launch Codex CLI
> Set Codex CLI permissions: 1. Allow Codex to modify files directly; 2. Codex requires manual authorization to modify files
> Note: After modifying the interface address, all models (including official preset models) will call the custom access point and will not use the official account quota.
#### 5. Linux Common Issues Resolution [#5-linux-common-issues-resolution]
??? example "Permission Error During Installation"
Try the following solutions:
* Install using `sudo`: `sudo npm install -g @openai/codex`
* Or configure `npm` to use the user directory: `npm config set prefix ~/.npm-global`
* Then add to `PATH`: `export PATH=~/.npm-global/bin:$PATH`
??? example "Missing Dependency Libraries"
Some Linux distributions require installing additional dependencies:
```
# Ubuntu/Debian
sudo apt install build-essential
```
```
# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```
# Factory Droid CLI (/en/apps/factory-droid-cli)
***
Command Line: Automation Across the SDLC. Script and parallelize Droids at massive scale for CI/CD, migrations, and maintenance. From automated code review to self-healing builds, integrate agents into every phase of development.
Droid CLI is a command-line tool developed by Factory AI, designed to operate as an AI software engineering agent. It allows users to interact with various large language models via the terminal, build, debug, and refactor code, and even create complete applications.
1. Official Homepage: [https://factory.ai/product/cli](https://factory.ai/product/cli)
2. Official Documentation: [https://docs.factory.ai/cli/getting-started/quickstart](https://docs.factory.ai/cli/getting-started/quickstart)
3. Installation Method: See the tutorial below on this page
## Demonstration [#demonstration]
***
### Features [#features]
| Category | Feature | Value/Capability | Example/Notes | |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------- |
| Quick Start & CLI | 30-second installation; launch droid interactive session in the project directory; supports macOS/Linux and Windows | Rapid integration into the current project, no new tools required | Windows Installation: \`irm [https://app.factory.ai/cli/windows](https://app.factory.ai/cli/windows) | iex`; Launch: `droid\` |
| End-to-End Feature Development | Full-process automation from planning to implementation to testing; transparent review process | Increase delivery speed while maintaining human control | Native diff viewing and approval workflow (see "Transparency and Control") | |
| Deep Codebase Understanding | Integrates shared organizational knowledge across codebases, documentation, and issue tracking; context-aware, performance improves over time | More accurate suggestions and changes | Continuously leverages knowledge across repositories and documentation | |
| Engineering System Integration | Natively integrates tools like Jira, Notion, Slack, etc.; development work stays synchronized with team processes | Reduce tool switching and information silos | "etc." indicates more integrations | |
| Production-Grade Automation | Workflows reusable locally and in CI/CD; built-in enterprise-grade security and compliance | Consistency and auditability | Adapts to pipelines and enterprise environments | |
| Enterprise Capabilities | Private deployment options, SOC-2 compliance, air-gapped environments | Meets security and compliance requirements | Prioritizing security and quality | |
| Existing Tool Enhancement | Works in terminals, IDEs, and existing development environments; no need to switch editors or learn new interfaces | Maintain existing work habits, low migration cost | Deep integration with familiar tools | |
| Transparency and Control | Every decision is visible and reviewable; maintain full oversight over code changes; native diff viewing and approval workflow | Reduce risk, enhance controllability | Audit-friendly, traceable | |
| Model Flexibility | Not locked to a single AI provider; select the best model per task; consistent organizational behavior and memory | Optimal choice between performance and cost | Supports multi-model routing | |
| Next Steps and Resources | Quickstart, Common Use Cases, IDE Integration, Configuration, AGENTS.md | Facilitates implementation and practice | See page “Next steps/Additional resources” | |
## AI Model Configuration Method [#ai-model-configuration-method]
### Windows Graphical Guide [#windows-graphical-guide]
#### 1. Open Terminal [#1-open-terminal]
#### 2. Install Factory Droid CLI [#2-install-factory-droid-cli]
Official one-click installation command:
```
irm https://app.factory.ai/cli/windows | iex
```
#### 3. Modify Configuration File [#3-modify-configuration-file]
Droid CLI requires modifying the configuration file to use third-party APIs.
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/factory-cli-setup.ps1')
```
#### 4. Start Using Droid CLI [#4-start-using-droid-cli]
You can now start using Droid CLI!
Launch Droid CLI directly:
```
# Launch Droid CLI
droid
```
Use in a specific project:
```
# Navigate to your project directory
cd C:\path\to\your\project
```
```
# Launch Droid CLI
droid
```
Press Enter to launch Droid CLI
Droid CLI requires users to log in to an official account (free) before use.
#### 5. Windows Common Issues Troubleshooting [#5-windows-common-issues-troubleshooting]
??? example "Error message "permission denied" during installation"
This is usually a permission issue. Try the following solutions:
* Run `PowerShell` as administrator
* Or configure `npm` to use the user directory: `npm config set prefix %APPDATA%\npm`
??? example "PowerShell Execution Policy Error"
If you encounter execution policy restrictions, run:
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### macOS/Linux Graphical Guide [#macoslinux-graphical-guide]
#### 1. Install Droid CLI [#1-install-droid-cli]
Open the terminal and run the following command:
```
curl -fsSL https://app.factory.ai/cli | sh
```
Modify environment variables according to the installation prompts (copy the installation prompt code directly):
For Linux, choose `~/.bashrc` or `~/.zshrc` as appropriate.
```
echo 'export PATH=/Users/修改此处/.local/bin:$PATH' >> ~/.zshrc
```
```
source ~/.zshrc
```
#### 2. Modify Configuration File [#2-modify-configuration-file]
Droid CLI requires modifying the configuration file to use third-party APIs.
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/factory-cli-setup.sh | bash
```
#### 3. Start Using Droid CLI [#3-start-using-droid-cli]
You can now start using Droid CLI!
Launch Droid CLI directly:
```
# Launch Droid CLI
droid
```
Use in a specific project:
```
# Navigate to your project directory
cd /path/to/your/project
```
```
# Launch Droid CLI
droid
```
Press Enter to launch Droid CLI
> Droid CLI requires users to log in to an official account (free) before use.
# FluentRead - Open Source Translation Plugin (/en/apps/fluent-read)
In the ZipFlow Console under System Settings -> Chat settings, you can add the following quick option to enable one-click fill to FluentRead from the API Keys page:
```json
{ "FluentRead": "fluentread" }
```
🌊 FluentRead is a revolutionary open-source browser translation plugin, enabling everyone to have a native-like reading experience.
* Project Address: [https://github.com/Bistutu/FluentRead](https://github.com/Bistutu/FluentRead)
## 🌟 Core Features [#-core-features]
### Intelligent Translation Engine [#intelligent-translation-engine]
* **Multi-engine Support**: Supports 20+ translation engines
* **Traditional Translation**: Microsoft Translator, Google Translate, DeepL, etc.
* **AI Large Models**: OpenAI, DeepSeek, Kimi, Ollama, etc.
* **Custom Engines**: Support for custom translation service configuration
### Immersive Reading Experience [#immersive-reading-experience]
* **Bilingual Display**: Original text and translation displayed side by side for easier reading
* **Word Selection Translation**: Select any text to get instant translation results
* **One-click Copy**: Quickly copy translations to improve reading efficiency
* **Full-page Translation**: Use the floating ball to translate entire web pages with one click, no page refresh needed
### Privacy and Customization [#privacy-and-customization]
* **Privacy Protection**: All data stored locally, open source and transparent code
* **Highly Customizable**: Rich customization options to meet different scenario needs
* **Completely Free**: Open source and free, non-commercial project
## 📦 Installation Methods [#-installation-methods]
| Browser | Installation Method |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Chrome** | [Chrome Web Store](https://chromewebstore.google.com/detail/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/djnlaiohfaaifbibleebjggkghlmcpcj?hl=zh-CN\&authuser=0) \| [Domestic Mirror](https://www.crxsoso.com/webstore/detail/djnlaiohfaaifbibleebjggkghlmcpcj) |
| **Edge** | [Edge Add-ons Store](https://microsoftedge.microsoft.com/addons/detail/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/kakgmllfpjldjhcnkghpplmlbnmcoflp?hl=zh-CN) |
| **Firefox** | [Firefox Add-ons Store](https://addons.mozilla.org/zh-CN/firefox/addon/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/) |
## 🚀 Configuration Methods [#-configuration-methods]
### Import Configuration from ZipFlow Console (Recommended) [#import-configuration-from-zipflow-console-recommended]
After installing the FluentRead plugin in your browser, open the ZipFlow Console->Token Management page and a prompt to add FluentRead will appear
Select a model and click "One-click Fill to FluentRead", which will pop up a confirmation window. Check if the corresponding information is correct
After confirming the import, the ZipFlow configuration in FluentRead will be enabled
### Manual Configuration in FluentRead [#manual-configuration-in-fluentread]
| Configuration Item | Content |
| ------------------- | ---------------------------------------- |
| Translation Service | ZipFlow |
| Access Token | ZipFlow Key |
| ZipFlow Interface | ZipFlow deployment address (without /v1) |
| Model | Select from list, or custom model |
| Custom Model | Model name |
# LangBot - IM Bot Development Platform (/en/apps/langbot)
LangBot is an open-source IM bot development platform that supports multiple instant messaging platforms such as Lark, DingTalk, WeChat, QQ, Telegram, Discord, Slack, and more. It integrates with globally leading AI models, supports knowledge bases, Agent, MCP, and various other AI application capabilities, and is perfectly compatible with ZipFlow.
* Official Website: [https://langbot.app/en](https://langbot.app/en)
* Download: [https://github.com/langbot-app/LangBot/releases](https://github.com/langbot-app/LangBot/releases)
* Official Documentation: [https://docs.langbot.app/en/insight/guide.html](https://docs.langbot.app/en/insight/guide.html)
* Open Source Repository: [https://github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot)
## Integrating with ZipFlow [#integrating-with-zipflow]
LangBot supports integration with locally deployed ZipFlow and third-party ZipFlow services built using ZipFlow.
### Usage Instructions [#usage-instructions]
1. Get API key from ZipFlow
For locally deployed ZipFlow, please configure the API address yourself (refer to [Container Network Connection](https://docs.langbot.app/en/workshop/network-details.html)). If using third-party ZipFlow services, you can copy the address from the page. Note that `/v1` needs to be added after the address.
2. Add a model in LangBot, select ZipFlow as the provider, and fill in the corresponding API key and API address
3. Select the model to use in the pipeline
4. Chat in the conversation debug or with the bot bound to the pipeline to use it
For deploying and configuring bots, please refer to [Deploy Bots](https://docs.langbot.app/en/deploy/platforms/readme.html).
### Using LangBot Knowledge Base [#using-langbot-knowledge-base]
LangBot supports using ZipFlow's embedding models as vector models for knowledge bases.
1. Add an embedding model in LangBot, select ZipFlow as the provider
2. Choose the embedding model when creating a new knowledge base
For more usage methods, please refer to LangBot's official documentation: [https://docs.langbot.app/en/insight/guide.html](https://docs.langbot.app/en/insight/guide.html)
# LunaTranslator - Open Source GalGame Translator (/en/apps/luna-translator)
In the ZipFlow dashboard, under `System Settings` -> `Chat Settings`, you can add the following shortcut option. This allows you to easily configure LunaTranslator with a single click from the Token Management page:
```json
{ "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" }
```
LunaTranslator is an open-source and free GalGame translator dedicated to providing a native-level GalGame gameplay experience.
* Project Repository: [https://github.com/HIllya51/LunaTranslator](https://github.com/HIllya51/LunaTranslator)
* Documentation：[https://docs.lunatranslator.org/zh/README.html](https://docs.lunatranslator.org/zh/README.html)
## Features [#features]
* **HOOK** Primarily uses HOOK to extract game text, compatible with almost all common and niche GalGames.
* **In-game Translation** Some games support direct in-game translation for an immersive experience.
* **Emulator HOOK** For most games on NS/PSP/PSV/PS2, it supports hooking emulators to directly read game text.
* **OCR** Features a built-in high-accuracy OCR model and supports many other online & offline OCR engines for flexible text extraction.
* **Rich Translation APIs** Supports almost all translation engines, including Large Language Models (LLMs), offline translation, etc.
* **Language Learning** Supports Japanese word segmentation and furigana annotation, AnkiConnect, and the Yomitan plugin.
* **Text-to-Speech (TTS)** Supports a large number of online & offline text-to-speech engines.
* **Speech Recognition** On Windows 10 and Windows 11, Windows Speech Recognition can be used.
## Installation [#installation]
Please download and install from the official documentation: [LunaTranslator Docs - Download & Launch & Update](https://docs.lunatranslator.org/en/README.html)
## Using ZipFlow in LunaTranslator [#using-zipflow-in-lunatranslator]
LunaTranslator supports integration with locally deployed ZipFlow instances and third-party services built on ZipFlow.
### One-Click Configuration [#one-click-configuration]
1. In the ZipFlow dashboard, go to `System Settings` -> `Chat Settings` and add the following shortcut option:
```json
{ "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" }
```
2. In the **`ZipFlow`** -> `Dashboard` -> `Token Management` tab, select the token you want to use in LunaTranslator. Click the dropdown option next to the chat button and select `LunaTranslator`. This will redirect you to the LunaTranslator application and automatically configure the API Address and API Key.
3. In **`LunaTranslator`** -> `Settings` -> `Translation Settings` -> `Large Language Model`, a new API configuration will be automatically added. Click the edit button to proceed.
4. Click the refresh button next to the **model** dropdown to fetch the list of models from the ZipFlow platform. Select or enter a model name, then click OK to save.
5. Check the toggle switch next to the **new\_api** large model configuration. If it's off, turn it on to start using the API.
### Manual Configuration [#manual-configuration]
1. In **`ZipFlow`** -> `CONSOLE` -> `Token Management` tab to get your API Key.
2. In **`LunaTranslator`** -> `Settings` -> `Translation Settings` -> `Large Language Model` and click "Add".
3. Copy the **Generic Large Model API** template to create a new API configuration.
4. In the **ZipFlow** configuration window, fill in your API Address and API Key.
5. Click the refresh button next to the **model** dropdown to fetch the list of models from the ZipFlow platform. Select or enter a model name, then click OK to save.
6. Click the toggle button next to **ZipFlow** to enable the API and start using it.
For more usage details, please refer to the official LunaTranslator documentation: [LunaTranslator Docs - Large Model Translation API](https://docs.lunatranslator.org/en/guochandamoxing.html)
# Anthropic Chat Format (Messages) (/en/api/anthropic-chat)
* [Anthropic Messages](https://docs.anthropic.com/en/api/messages)
* [Anthropic Streaming Messages](https://docs.anthropic.com/en/api/messages-streaming)
## 📝 Introduction [#-introduction]
Given a list of structured input messages containing text and/or image content, the model will generate the next message in the conversation. The Messages API can be used for single queries or stateless multi-turn conversations.
## 💡 Request Examples [#-request-examples]
### Basic Text Chat ✅ [#basic-text-chat-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}'
```
**Response Example:**
```json
{
"content": [
{
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2095,
"output_tokens": 503
}
}
```
### Image Analysis Chat ✅ [#image-analysis-chat-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "What's in this image?"
}
]
}
]
}'
```
**Response Example:**
```json
{
"content": [
{
"text": "This image shows an orange cat sunbathing on a windowsill. The cat looks very relaxed, squinting its eyes while enjoying the sunlight. Some green plants can be seen outside the window.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 3050,
"output_tokens": 892
}
}
```
### Tool Calling ✅ [#tool-calling-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": "What's the weather like in Beijing today?"
}
],
"tools": [
{
"name": "get_weather",
"description": "Get the current weather for a specified location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name, e.g.: Beijing"
}
},
"required": ["location"]
}
}
]
}'
```
**Response Example:**
```json
{
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "Beijing" }
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "tool_use",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2156,
"output_tokens": 468
}
}
```
### Streaming Response ✅ [#streaming-response-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": "Tell me a story"
}
],
"stream": true
}'
```
**Response Example:**
```json
{
"type": "message_start",
"message": {
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"type": "message"
}
}
{
"type": "content_block_start",
"index": 0,
"content_block": {
"type": "text"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "从前"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "有一只"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "小兔子..."
}
}
{
"type": "content_block_stop",
"index": 0
}
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"usage": {
"input_tokens": 2045,
"output_tokens": 628
}
}
}
{
"type": "message_stop"
}
```
## 📮 Request [#-request]
### Endpoints [#endpoints]
```
POST /v1/messages
```
### Authentication Method [#authentication-method]
Include the following in the request headers for API key authentication:
```
x-api-key: $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key. You can obtain an API key from the console, and each key is limited to one workspace.
### Request Headers [#request-headers]
#### `anthropic-beta` [#anthropic-beta]
* Type: String
* Required: No
Specify the beta version to use, supported by comma-separated lists like `beta1,beta2`, or specify this header multiple times.
#### `anthropic-version` [#anthropic-version]
* Type: String
* Required: Yes
Specify the API version to use.
### Request Body Parameters [#request-body-parameters]
#### `max_tokens` [#max_tokens]
* Type: Integer
* Required: Yes
The maximum number of tokens to generate. Different models have different limits, see model documentation. Range `x > 1`.
#### `messages` [#messages]
* Type: Array of objects
* Required: Yes
The input message list. The model is trained to alternate between user and assistant in the conversation. When creating a new message, you can use the `messages` parameter to specify previous conversation turns, and the model will generate the next message in the conversation. Consecutive user or assistant messages are merged into a single turn.
Each message must contain `role` and `content` fields. You can specify a single user role message, or include multiple user and assistant messages. If the last message uses the assistant role, the response content will continue directly from the content of that message, which can be used to constrain the model's response.
**Single User Message Example:**
```json
[{"role": "user", "content": "Hello, Claude"}]
```
**Multi-turn Conversation Example:**
```json
[
{"role": "user", "content": "你好。"},
{"role": "assistant", "content": "你好！我是 Claude。有什么可以帮你的吗？"},
{"role": "user", "content": "请用简单的话解释什么是 LLM？"}
]
```
**Partially Filled Response Example:**
```json
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
```
Each message's content can be a string or an array of content blocks. Using a string is equivalent to a shorthand for an array of "text" type content blocks. The following two statements are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{
"role": "user",
"content": [{"type": "text", "text": "Hello, Claude"}]
}
```
Starting from Claude 3 model, you can also send image content blocks:
```json
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "What's in this image?"
}
]
}
```
> Currently supported image formats include: base64, image/jpeg, image/png, image/gif, and image/webp.
##### `messages.role` [#messagesrole]
* Type: String
* Required: Yes
* Optional Values: user, assistant
Note: The Messages API does not have a "system" role, if a system prompt is needed, please use the top-level `system` parameter.
##### `messages.content` [#messagescontent]
* Type: String or Array of objects
* Required: Yes
The content of a message can be one of the following types:
###### Text Content (Text) [#text-content-text]
```json
{
"type": "text", // Required, enum value: "text"
"text": "Hello, Claude", // Required, minimum length: 1
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
}
```
###### Image Content (Image) [#image-content-image]
```json
{
"type": "image", // Required, enum value: "image"
"source": { // Required
"type": "base64", // Required, enum value: "base64"
"media_type": "image/jpeg", // Required, supported: image/jpeg, image/png, image/gif, image/webp
"data": "/9j/4AAQSkZJRg..." // Required, base64 encoded image data
},
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
}
```
###### Tool Use (Tool Use) [#tool-use-tool-use]
```json
{
"type": "tool_use", // Required, enum value: "tool_use", default value
"id": "toolu_xyz...", // Required, unique identifier for tool use
"name": "get_weather", // Required, tool name, minimum length: 1
"input": { // Required, object containing tool input parameters
// Tool input parameters, specific format defined by tool's input_schema
},
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
}
```
###### Tool Result (Tool Result) [#tool-result-tool-result]
```json
{
"type": "tool_result", // Required, enum value: "tool_result"
"tool_use_id": "toolu_xyz...", // Required
"content": "Result content", // Required, can be string or array of content blocks
"is_error": false, // Optional, boolean
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
}
```
When content is an array of content blocks, each content block can be text or image:
```json
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": [
{
"type": "text", // Required, enum value: "text"
"text": "Analysis result", // Required, minimum length: 1
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
},
{
"type": "image", // Required, enum value: "image"
"source": { // Required
"type": "base64", // Required, enum value: "base64"
"media_type": "image/jpeg",
"data": "..."
},
"cache_control": {
"type": "ephemeral"
}
}
]
}
```
###### Document (Document) [#document-document]
```json
{
"type": "document", // Required, enum value: "document"
"source": { // Required
// Document source data
},
"cache_control": {
"type": "ephemeral" // Optional, enum value: "ephemeral"
}
}
```
Note:
1. Each type can optionally include a `cache_control` field to control content caching
2. The minimum length of text content is 1
3. All type fields are required enum strings
4. The `content` field of tool results supports string or array of content blocks containing text/image
#### `model` [#model]
* Type: String
* Required: Yes
The model name to use, see model documentation. Range `1 - 256` characters.
#### `metadata` [#metadata]
* Type: Object
* Required: No
An object describing the request metadata. Includes the following optional fields:
* `user_id`: An external identifier for the user associated with the request. It should be a uuid, hash, or other opaque identifier. Do not include any identifying information such as name, email, or phone number. Maximum length: 256.
#### `stop_sequences` [#stop_sequences]
* Type: Array of strings
* Required: No
Custom text sequences to stop generation.
#### `stream` [#stream]
* Type: Boolean
* Required: No
Whether to use server-sent events (SSE) to incrementally return response content.
#### `system` [#system]
* Type: String
* Required: No
System prompt, provides background and instructions to Claude. This is a way to provide context and specific goals or roles to the model. Note that this is different from the `role` in messages, and the Messages API does not have a "system" role.
#### `temperature` [#temperature]
* Type: Number
* Required: No
* Default: 1.0
Controls the randomness of generation, 0.0 - 1.0. Range `0 < x < 1`. It is recommended to use a value close to 0.0 for analytical/multiple-choice tasks, and a value close to 1.0 for creative and generative tasks.
Note: Even if temperature is set to 0.0, the result will not be completely deterministic.
#### 🆕 `thinking` [#-thinking]
* Type: Object
* Required: No
Configures Claude's extended thinking function. When enabled, the response will include content blocks showing Claude's thought process before giving the final answer. Requires at least 1,024 tokens of budget and is counted towards your max\_tokens limit.
Can be set to one of the following two modes:
##### 1. Enabled Mode [#1-enabled-mode]
```json
{
"type": "enabled",
"budget_tokens": 2048
}
```
* `type`: Required, enum value: "enabled"
* `budget_tokens`: Required, integer. Determines the number of tokens that Claude can use for internal reasoning processes. A larger budget allows the model to perform more in-depth analysis on complex questions, improving response quality. Must be ≥1024 and less than max\_tokens. Range `x > 1024`.
##### 2. Disabled Mode [#2-disabled-mode]
```json
{
"type": "disabled"
}
```
* `type`: Required, enum value: "disabled"
#### `tool_choice` [#tool_choice]
* Type: Object
* Required: No
Controls how the model uses the provided tools. Can be one of the following three types:
##### 1. Auto Mode (Automatic Selection) [#1-auto-mode-automatic-selection]
```json
{
"type": "auto", // Required, enum value: "auto"
"disable_parallel_tool_use": false // Optional, default false. If true, the model will only use one tool at most
}
```
##### 2. Any Mode (Any Tool) [#2-any-mode-any-tool]
```json
{
"type": "any", // Required, enum value: "any"
"disable_parallel_tool_use": false // Optional, default false. If true, the model will exactly use one tool
}
```
##### 3. Tool Mode (Specific Tool) [#3-tool-mode-specific-tool]
```json
{
"type": "tool", // Required, enum value: "tool"
"name": "get_weather", // Required, specify the tool name to use
"disable_parallel_tool_use": false // Optional, default false. If true, the model will exactly use one tool
}
```
Note:
1. Auto Mode: The model can decide whether to use tools on its own
2. Any Mode: The model must use tools, but can choose any available tool
3. Tool Mode: The model must use the specified tool
#### `tools` [#tools]
* Type: Array of objects
* Required: No
Defines the tools that the model might use. Tools can be custom tools or built-in tool types:
##### 1. Custom Tool (Tool) [#1-custom-tool-tool]
Each custom tool definition includes:
* `type`: Optional, enum value: "custom"
* `name`: Tool name, required, 1-64 characters
* `description`: Tool description, recommended to be as detailed as possible
* `input_schema`: JSON Schema definition for tool input, required
* `cache_control`: Cache control, optional, type is "ephemeral"
Example:
```json
[
{
"type": "custom",
"name": "get_weather",
"description": "Get the current weather for a specified location",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name, e.g.: Beijing"
}
},
"required": ["location"]
}
}
]
```
##### 2. Computer Tool (ComputerUseTool) [#2-computer-tool-computerusetool]
```json
{
"type": "computer_20241022", // Required
"name": "computer", // Required, enum value: "computer"
"display_width_px": 1024, // Required, display width (pixels)
"display_height_px": 768, // Required, display height (pixels)
"display_number": 0, // Optional, X11 display number
"cache_control": {
"type": "ephemeral" // Optional
}
}
```
##### 3. Bash Tool (BashTool) [#3-bash-tool-bashtool]
```json
{
"type": "bash_20241022", // Required
"name": "bash", // Required, enum value: "bash"
"cache_control": {
"type": "ephemeral" // Optional
}
}
```
##### 4. Text Editor Tool (TextEditor) [#4-text-editor-tool-texteditor]
```json
{
"type": "text_editor_20241022", // Required
"name": "str_replace_editor", // Required, enum value: "str_replace_editor"
"cache_control": {
"type": "ephemeral" // Optional
}
}
```
When the model uses a tool, it returns a tool\_use content block:
```json
[
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "Beijing" }
}
]
```
You can execute a tool and return the result via a tool\_result content block:
```json
[
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"content": "The weather in Beijing today is sunny, with a temperature of 25°C"
}
]
```
#### `top_k` [#top_k]
* Type: Integer
* Required: No
* Range: x > 0
Samples from the top K options of tokens. Used to remove "long tail" responses with low probabilities. It is recommended to only use this in advanced use cases, usually only adjusting temperature is sufficient.
#### `top_p` [#top_p]
* Type: Number
* Required: No
* Range: 0 \< x \< 1
Uses nucleus sampling. Calculates the cumulative distribution of probabilities for each subsequent token in descending order, truncates when the probability reaches the specified top\_p. It is recommended to adjust only one of temperature or top\_p, not both.
## 📥 Response [#-response]
### Successful Response [#successful-response]
Returns a chat completion object, containing the following fields:
#### `content` [#content]
* Type: Array of objects
* Required: Yes
The content generated by the model, consisting of multiple content blocks. Each content block has a type that determines its shape. Content blocks can be one of the following types:
##### Text Content Block (Text) [#text-content-block-text]
```json
{
"type": "text", // Required, enum value: "text", default value
"text": "你好，我是 Claude。" // Required, maximum length: 5000000, minimum length: 1
}
```
##### Tool Use Content Block (Tool Use) [#tool-use-content-block-tool-use]
```json
{
"type": "tool_use", // Required, enum value: "tool_use", default value
"id": "toolu_xyz...", // Required, unique identifier for tool use
"name": "get_weather", // Required, tool name, minimum length: 1
"input": { // Required, object containing tool input parameters
// Tool input parameters, specific format defined by tool's input_schema
}
}
```
Example:
```json
// Text content example
[{"type": "text", "text": "你好，我是 Claude。"}]
// Tool use example
[{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "Beijing" }
}]
// Mixed content example
[
{"type": "text", "text": "根据天气查询结果："},
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "Beijing" }
}
]
```
If the last message in the request was an assistant role, the response content will continue directly from that message. For example:
```json
// Request
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
// Response
[{"type": "text", "text": "B)"}]
```
#### `id` [#id]
* Type: String
* Required: Yes
The unique identifier for the response.
#### `model` [#model-1]
* Type: String
* Required: Yes
The model name used.
#### `role` [#role]
* Type: String
* Required: Yes
* Default: assistant
The session role for the generated message, always "assistant".
#### `stop_reason` [#stop_reason]
* Type: String or null
* Required: Yes
The reason for stopping generation, possible values include:
* `"end_turn"`: Model reached a natural stopping point
* `"max_tokens"`: Exceeded requested max\_tokens or model's maximum limit
* `"stop_sequence"`: Generated one of the custom stop sequences
* `"tool_use"`: Model called one or more tools
This value is always non-empty in non-streaming mode. In streaming mode, it is null in the `message_start` event, and non-null otherwise.
#### `stop_sequence` [#stop_sequence]
* Type: String or null
* Required: Yes
The generated custom stop sequence. If the model encountered one of the stop\_sequences specified in the `stop_sequences` parameter, this field will contain that matching stop sequence. If not stopped by a stop sequence, it is null.
#### `type` [#type]
* Type: String
* Required: Yes
* Default: message
* Optional: message
Object type, always "message" for Messages.
#### `usage` [#usage]
* Type: Object
* Required: Yes
Usage statistics related to billing and rate limits. Includes the following fields:
* `input_tokens`: Number of input tokens used, required, range x > 0
* `output_tokens`: Number of output tokens used, required, range x > 0
* `cache_creation_input_tokens`: Number of input tokens used to create cache entries (if applicable), required, range x > 0
* `cache_read_input_tokens`: Number of input tokens read from cache (if applicable), required, range x > 0
Note: Due to API internal transformations and parsing, token counts may not exactly correspond to the actual visible content of requests and responses. For example, even an empty string response will have a non-zero output\_tokens value.
### Error Response [#error-response]
When a request encounters an issue, the API will return an error response object, with HTTP status codes in the 4XX-5XX range.
#### Common Error Status Codes [#common-error-status-codes]
* `401 Unauthorized`: Invalid API key or not provided
* `400 Bad Request`: Invalid request parameters
* `429 Too Many Requests`: Exceeded API call limit
* `500 Internal Server Error`: Server internal error
Error response example:
```json
{
"error": {
"type": "invalid_request_error",
"message": "Invalid API key provided",
"code": "invalid_api_key"
}
}
```
Main error types:
* `invalid_request_error`: Request parameter error
* `authentication_error`: Authentication related error
* `rate_limit_error`: Request frequency exceeded
* `server_error`: Server internal error
# Cohere Rerank Format (/en/api/cohere-rerank)
The interface format of Cohere's Rerank model is the same as [Jina's Rerank model interface](/en/api/jinaai-rerank).
[Cohere Rerank](https://docs.cohere.com/reference/rerank)
## 📝 Introduction [#-introduction]
Given a query and a list of texts, the Rerank API will sort the texts based on their relevance to the query. Each text is assigned a relevance score, resulting in an ordered array of results. This feature is especially useful for search and retrieval applications, optimizing document ranking and helping users find relevant information faster.
## 💡 Request Examples [#-request-examples]
### Basic Rerank Request ✅ [#basic-rerank-request-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "rerank-v3.5",
"query": "What is the capital of the United States?",
"documents": [
"The capital of Nevada is Carson City.",
"The Northern Mariana Islands are a group of islands in the Pacific, with Saipan as the capital.",
"Washington, D.C. (also known as Washington or D.C., officially the District of Columbia) is the capital of the United States.",
"Capitalization in English grammar is the use of uppercase letters at the beginning of words. English usage differs from other languages in capitalization.",
"The death penalty existed in the United States before it became a country. As of 2017, 30 out of 50 states have the death penalty legalized."
],
"top_n": 3
}'
```
**Response Example:**
```json
{
"results": [
{
"index": 2,
"relevance_score": 0.999071
},
{
"index": 0,
"relevance_score": 0.32713068
},
{
"index": 1,
"relevance_score": 0.1867867
}
],
"id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
"meta": {
"api_version": {
"version": "2",
"is_experimental": false
},
"billed_units": {
"search_units": 1
}
}
}
```
### Using Structured Data ✅ [#using-structured-data-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "rerank-v3.5",
"query": "Looking for a cost-effective DSLR camera for beginners",
"documents": [
"Model: Canon EOS 800D\nPrice: 4299 yuan\nFeatures: 24.1MP, optical viewfinder, Wi-Fi\nSuitable for: Beginners, enthusiasts",
"Model: Nikon D3500\nPrice: 3099 yuan\nFeatures: 24.16MP, optical viewfinder, battery life up to 1550 shots\nSuitable for: Newbies, students",
"Model: Sony A7III\nPrice: 12999 yuan\nFeatures: 24.2MP, full-frame, 4K video\nSuitable for: Professional photographers, video creators"
],
"max_tokens_per_doc": 512
}'
```
**Response Example:**
```json
{
"results": [
{
"index": 1,
"relevance_score": 0.918472
},
{
"index": 0,
"relevance_score": 0.854321
},
{
"index": 2,
"relevance_score": 0.423156
}
],
"id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa",
"meta": {
"api_version": {
"version": "2"
},
"billed_units": {
"search_units": 1
}
}
}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/rerank
```
Sort a list of texts based on their relevance to the query.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Header Parameters [#request-header-parameters]
#### `X-Client-Name` [#x-client-name]
* Type: String
* Required: No
* Description: Project name initiating the request.
### Request Body Parameters [#request-body-parameters]
#### `model` [#model]
* Type: String
* Required: Yes
* Description: Model identifier to use, e.g., rerank-v3.5.
#### `query` [#query]
* Type: String
* Required: Yes
* Description: Search query text. This is the user's question or query content.
#### `documents` [#documents]
* Type: Array of strings
* Required: Yes
* Description: List of texts to compare with the query. For best performance, do not send more than 1,000 documents in a single request.
* Notes:
* Long documents will be automatically truncated to the value specified by max\_tokens\_per\_doc
* Structured data should be formatted as YAML strings for best performance
#### `top_n` [#top_n]
* Type: Integer
* Required: No
* Description: Limit the number of reranked results returned. If not specified, all reranked results will be returned.
#### `max_tokens_per_doc` [#max_tokens_per_doc]
* Type: Integer
* Required: No
* Default: 4096
* Description: Long documents will be automatically truncated to the specified number of tokens.
## 📥 Response [#-response]
### Successful Response [#successful-response]
Returns an object containing the sorted list of documents.
#### `results` [#results]
* Type: Array of objects
* Description: List of sorted documents, in descending order of relevance
* Properties:
* `index`: Integer, the index of the document in the original list
* `relevance_score`: Float, relevance score in the range \[0, 1]. A score close to 1 indicates high relevance, close to 0 indicates low relevance
#### `id` [#id]
* Type: String
* Description: Unique identifier for the request
#### `meta` [#meta]
* Type: Object
* Description: Contains metadata about the request
* Properties:
* `api_version`: Object, contains API version info
* `version`: String, API version number
* `is_deprecated`: Boolean, whether deprecated
* `is_experimental`: Boolean, whether experimental
* `billed_units`: Object, contains billing info
* `search_units`: Float, number of billed search units
* `tokens`: Object, contains token usage statistics
* `input_tokens`: Float, number of tokens as model input
* `output_tokens`: Float, number of tokens generated by the model
#### `warnings` [#warnings]
* Type: Array of strings
* Required: No
* Description: Warning messages returned by the API
### Error Response [#error-response]
When a request encounters an issue, the API may return the following HTTP status codes and corresponding errors:
* `400 Bad Request`: Request format or parameter error
* `401 Unauthorized`: No valid API key provided
* `403 Forbidden`: No permission to access this resource
* `404 Not Found`: Requested resource does not exist
* `422 Unprocessable Entity`: Request is well-formed but contains semantic errors
* `429 Too Many Requests`: Request rate exceeds the limit
* `500 Internal Server Error`: Server internal error
* `503 Service Unavailable`: Service temporarily unavailable
## 🌟 Best Practices [#-best-practices]
### Document Preparation Tips [#document-preparation-tips]
1. **Document Length**: Keep each document concise and clear, avoid being too long. Long documents will be automatically truncated.
2. **Structured Data**: Format structured data as YAML strings for best performance. For example:
```yaml
title: Product Name
price: 9999 yuan
features:
- Feature 1
- Feature 2
```
3. **Number of Documents**: Do not exceed 1,000 documents per request for best performance.
### Query Optimization [#query-optimization]
1. **Be Specific**: Formulate clear and specific queries for more accurate ranking results.
2. **Avoid Vague Queries**: Avoid overly vague or generic queries, as this may result in less distinct relevance scores.
### Understanding Relevance Scores [#understanding-relevance-scores]
Relevance scores are normalized to the range \[0, 1]:
* Scores close to 1 indicate high relevance to the query
* Scores close to 0 indicate low relevance
# Deepseek Reasoning Chat Format (Reasoning Content) (/en/api/deepseek-reasoning-chat)
[Reasoning Model (deepseek-reasoner)](https://api-docs.deepseek.com/en/guides/reasoning_model)
## 📝 Introduction [#-introduction]
Deepseek-reasoner is a reasoning model launched by DeepSeek. Before outputting the final answer, the model will first output a chain-of-thought (reasoning content) to improve the accuracy of the final answer. The API exposes the deepseek-reasoner chain-of-thought content for users to view, display, or distill.
## 💡 Request Examples [#-request-examples]
### Basic Text Chat ✅ [#basic-text-chat-]
```bash
curl https://api.deepseek.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "deepseek-reasoner",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
],
"max_tokens": 4096
}'
```
**Response Example:**
```json
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "deepseek-reasoner",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": "Let me think step by step:\n1. We need to compare 9.11 and 9.8\n2. Both numbers are decimals, we can compare directly\n3. 9.8 = 9.80\n4. 9.11 < 9.80\n5. So 9.8 is greater",
"content": "9.8 is greater than 9.11."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 15,
"total_tokens": 25
}
}
```
### Streaming Response ✅ [#streaming-response-]
```bash
curl https://api.deepseek.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "deepseek-reasoner",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
],
"stream": true
}'
```
**Streaming Response Example:**
```jsonl
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"role":"assistant","reasoning_content":"Let me"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":"think step by step"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":":"},"finish_reason":null}]}
// ... more reasoning content ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":"9.8"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":" is greater"},"finish_reason":null}]}
// ... more final answer content ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/chat/completions
```
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$DEEPSEEK_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### `messages` [#messages]
* Type: Array
* Required: Yes
The list of messages in the conversation so far. Note: If you pass reasoning\_content in the input messages sequence, the API will return a 400 error.
#### `model` [#model]
* Type: String
* Required: Yes
* Value: deepseek-reasoner
The model ID to use. Currently only deepseek-reasoner is supported.
#### `max_tokens` [#max_tokens]
* Type: Integer
* Required: No
* Default: 4096
* Max: 8192
The maximum length of the final answer (excluding reasoning content). Note: The output of the reasoning content can be up to 32K tokens.
#### `stream` [#stream]
* Type: Boolean
* Required: No
* Default: false
Whether to use streaming response.
### Unsupported Parameters [#unsupported-parameters]
The following parameters are currently not supported:
* temperature
* top\_p
* presence\_penalty
* frequency\_penalty
* logprobs
* top\_logprobs
Note: For compatibility with existing software, setting temperature, top\_p, presence\_penalty, frequency\_penalty will not cause an error, but will not take effect. Setting logprobs or top\_logprobs will cause an error.
### Supported Features [#supported-features]
* Chat completion
* Chat prefix continuation (Beta)
### Unsupported Features [#unsupported-features]
* Function Call
* Json Output
* FIM Completion (Beta)
## 📥 Response [#-response]
### Successful Response [#successful-response]
Returns a chat completion object. If the request is streamed, returns a streaming sequence of chat completion chunk objects.
#### `id` [#id]
* Type: String
* Description: Unique identifier for the response
#### `object` [#object]
* Type: String
* Description: Object type, value is "chat.completion"
#### `created` [#created]
* Type: Integer
* Description: Response creation timestamp
#### `model` [#model-1]
* Type: String
* Description: Model name used, value is "deepseek-reasoner"
#### `choices` [#choices]
* Type: Array
* Description: Contains generated reply options
* Properties:
* `index`: Option index
* `message`: Message object containing role, reasoning content, and final answer
* `role`: Role, value is "assistant"
* `reasoning_content`: Chain-of-thought content
* `content`: Final answer content
* `finish_reason`: Finish reason
#### `usage` [#usage]
* Type: Object
* Description: Token usage statistics
* Properties:
* `prompt_tokens`: Number of tokens used for prompt
* `completion_tokens`: Number of tokens used for completion
* `total_tokens`: Total number of tokens
## 📝 Context Concatenation Explanation [#-context-concatenation-explanation]
In each round of conversation, the model outputs reasoning\_content (chain-of-thought) and the final answer (content). In the next round of conversation, the reasoning\_content output from the previous round will NOT be concatenated into the context, as shown below:
If you pass reasoning\_content in the input messages sequence, the API will return a 400 error. Therefore, please remove the reasoning\_content field from the API response before making the next API request, as shown in the usage example below.
Usage Example:
```python
from openai import OpenAI
client = OpenAI(api_key="", base_url="https://api.deepseek.com")
# First round of conversation
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages
)
reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content
# Second round of conversation - only concatenate the final answer content
messages.append({'role': 'assistant', 'content': content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages
)
```
Streaming response example:
```python
# First round of conversation
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages,
stream=True
)
reasoning_content = ""
content = ""
for chunk in response:
if chunk.choices[0].delta.reasoning_content:
reasoning_content += chunk.choices[0].delta.reasoning_content
else:
content += chunk.choices[0].delta.content
# Second round of conversation - only concatenate the final answer content
messages.append({"role": "assistant", "content": content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages,
stream=True
)
```
# Video Generation API (/en/api/generate-video)
Call the video generation interface to generate videos, supporting various video generation services:
* **Kling AI (Kling)**: [API Documentation](https://app.klingai.com/cn/dev/document-api/apiReference/commonInfo)
* **Jimeng**: [API Documentation](https://www.volcengine.com/docs/85621/1538636)
* **Gemini**: Google's video generation service
* **Vidu**: High-quality video generation service
## ZipFlow Video Generation Format [#zipflow-video-generation-format]
### API Endpoint [#api-endpoint]
```
POST /v1/video/generations
```
### Request Headers [#request-headers]
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------- |
| Authorization | string | Yes | User Authentication Token (Bearer: sk-xxxx) |
| Content-Type | string | Yes | application/json |
### Request Parameters [#request-parameters]
| Parameter | Type | Required | Description |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| model | string | Yes | Model/Style ID |
| prompt | string | Yes | Text Prompt |
| duration | number | No | Video Duration (seconds) |
| fps | integer | No | Video Frame Rate (FPS) |
| height | integer | No | Video Height |
| width | integer | No | Video Width |
| image | string | No | Image Input (URL/Base64) |
| metadata | object | No | Vendor-specific/Custom Parameters (e.g., negative\_prompt, style, quality\_level, etc.) |
| n | integer | No | Number of Videos to Generate |
| response\_format | string | No | Response Format |
| seed | integer | No | Random Seed |
| user | string | No | User Identifier |
### Request Examples [#request-examples]
#### Kling AI Example [#kling-ai-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-v1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"duration": 5,
"metadata": {
"seed": 20231234,
"negative_prompt": "模糊",
"image_tail": "https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png"
}
}'
```
#### Jimeng AI Example [#jimeng-ai-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "一个穿着宇航服的宇航员在月球上行走",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": [
"https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg"
],
"aspect_ratio": "16:9"
}
}'
```
#### Vidu Channel Example [#vidu-channel-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png",
"duration": 5,
"metadata": {
"duration": 5,
"seed": 0,
"resolution": "1080p",
"movement_amplitude": "auto",
"bgm": false,
"payload": "",
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
### Response Format [#response-format]
#### 201 - Created Successfully [#201---created-successfully]
```json
{
"id": "video_123",
"object": "video",
"model": "kling-v1",
"created_at": 1640995200,
"task_id": "abcd1234efgh",
"status": "processing"
}
```
#### Response Field Description [#response-field-description]
| Field | Type | Description |
| ----------- | ------- | ------------------------------------- |
| id | string | Video Task ID |
| object | string | Object type, fixed as "video" |
| model | string | Name of the model used |
| created\_at | integer | Creation Timestamp |
| task\_id | string | Task ID, used for status query |
| status | string | Task Status (processing: in progress) |
## Error Responses [#error-responses]
### 400 - Request Parameter Error [#400---request-parameter-error]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - Unauthorized [#401---unauthorized]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - Forbidden [#403---forbidden]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 500 - Internal Server Error [#500---internal-server-error]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
## Supported Models [#supported-models]
### Kling AI (Kling) [#kling-ai-kling]
* `kling-v1`: Text-to-Video Model
* `kling-v2-master`: Image-to-Video Model
### Jimeng [#jimeng]
* `jimeng_vgfm_t2v_l20`: Text-to-Video Model
* `jimeng_vgfm_i2v_l20`: Image-to-Video Model
### Vidu [#vidu]
* `viduq1`: Vidu High-Quality Video Generation Model
## Best Practices [#best-practices]
1. **Prompt Optimization**: Use detailed, specific descriptive words, including style and quality requirements
2. **Image Quality**: Use high-resolution, clear images for image-to-video generation
3. **Parameter Tuning**: Adjust parameters like duration and resolution according to requirements
4. **Error Handling**: Implement appropriate retry mechanisms and error handling
5. **Asynchronous Processing**: Video generation is an asynchronous task, requiring polling for status checks
# Google Gemini Chat Format (Generate Content) (/en/api/google-gemini-chat)
[Google Gemini Generating content API](https://ai.google.dev/api/generate-content)
## 📝 Introduction [#-introduction]
Google Gemini API supports generating content using images, audio, code, tools, etc. Given input GenerateContentRequest generates model responses. Supports text generation, visual understanding, audio processing, long context, code execution, JSON schema, function calling, and many other features.
## 💡 Request Examples [#-request-examples]
### Basic Text Chat ✅ [#basic-text-chat-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[{"text": "Write a story about a magic backpack."}]
}]
}' 2> /dev/null
```
### Image Analysis Chat ✅ [#image-analysis-chat-]
```bash
# Use temporary file to save base64 encoded image data
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
# Use temporary file to save JSON payload
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT
cat > "$TEMP_JSON" << EOF
{
"contents": [{
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
]
}]
}
EOF
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
```
### Function Calling ✅ [#function-calling-]
```bash
cat > tools.json << EOF
{
"function_declarations": [
{
"name": "enable_lights",
"description": "Turn on the lighting system."
},
{
"name": "set_light_color",
"description": "Set the light color. Lights must be enabled for this to work.",
"parameters": {
"type": "object",
"properties": {
"rgb_hex": {
"type": "string",
"description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
}
},
"required": [
"rgb_hex"
]
}
},
{
"name": "stop_lights",
"description": "Turn off the lighting system."
}
]
}
EOF
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d @<(echo '
{
"system_instruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(cat tools.json)'],
"tool_config": {
"function_calling_config": {"mode": "auto"}
},
"contents": {
"role": "user",
"parts": {
"text": "Turn on the lights please."
}
}
}
') 2>/dev/null |sed -n '/"content"/,/"finishReason"/p'
```
### JSON Schema Response ✅ [#json-schema-response-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{
"parts":[
{"text": "List 5 popular cookie recipes"}
]
}],
"generationConfig": {
"response_mime_type": "application/json",
"response_schema": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"recipe_name": {"type":"STRING"},
}
}
}
}
}' 2> /dev/null | head
```
### Audio Processing 🟡 [#audio-processing-]
Only supports uploading audio via `inline_data` in base64 format, does not support `file_data.file_uri` or File API.
```bash
# Use File API to upload audio data to API request
# Use base64 inline_data to upload audio data to API request
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Please describe this audio file."},
{"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### Video Processing 🟡 [#video-processing-]
Only supports uploading video via `inline_data` in base64 format, does not support `file_data.file_uri` or File API.
```bash
# Use File API to upload video data to API request
# Use base64 inline_data to upload video data to API request
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Transcribe the audio from this video and provide visual descriptions."},
{"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### PDF Processing 🟡 [#pdf-processing-]
仅支持通过 `inline_data` 以 base64 方式上传 PDF，不支持 `file_data.file_uri` 或 File API。
```bash
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# 使用 base64 inline_data 上传 PDF 文件到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")
echo $MIME_TYPE
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Can you add a few more lines to this poem?"},
{"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### Chat Dialog ✅ [#chat-dialog-]
```bash
curl https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{"role":"user",
"parts":[{
"text": "Hello"}]},
{"role": "model",
"parts":[{
"text": "Great to meet you. What would you like to know?"}]},
{"role":"user",
"parts":[{
"text": "I have two dogs in my house. How many paws are in my house?"}]},
]
}' 2> /dev/null | grep "text"
```
### Streaming Response ✅ [#streaming-response-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"contents": [{
"parts": [{"text": "写一个关于魔法背包的故事"}]
}]
}'
```
### Code Execution ✅ [#code-execution-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "计算斐波那契数列的第10项"}]
}],
"tools": [{
"codeExecution": {}
}]
}'
```
### Generation Config ✅ [#generation-config-]
```bash
curl https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Explain how AI works"}
]
}],
"generationConfig": {
"stopSequences": [
"Title"
],
"temperature": 1.0,
"maxOutputTokens": 800,
"topP": 0.8,
"topK": 10
}
}' 2> /dev/null | grep "text"
```
### Safety Settings ✅ [#safety-settings-]
```bash
echo '{
"safetySettings": [
{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
],
"contents": [{
"parts":[{
"text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d @request.json 2> /dev/null
```
### System Instruction ✅ [#system-instruction-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
"parts": {
"text": "Hello there"}}}'
```
## 📮 Request [#-request]
### Endpoints [#endpoints]
#### Generate Content [#generate-content]
```
POST https://api.zipflow.xyz/v1beta/{model=models/*}:generateContent
```
#### Stream Generate Content [#stream-generate-content]
```
POST https://api.zipflow.xyz/v1beta/{model=models/*}:streamGenerateContent
```
### Authentication Method [#authentication-method]
Include API key in the request URL:
```
?key=$ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your Google AI API key.
### Path Parameters [#path-parameters]
#### `model` [#model]
* Type: string
* Required: yes
The name of the model to generate completions for.
Format: `models/{model}`, e.g. `models/gemini-2.0-flash`
### Request Body Parameters [#request-body-parameters]
#### `contents` [#contents]
* Type: array
* Required: yes
The content of the current conversation with the model. For a single-turn query, this is a single instance. For chat-like multi-turn queries, this is a repeated field containing the conversation history and the latest request.
**Content object properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `parts` | array | yes | Ordered content parts that make up a single message |
| `role` | string | no | The producer of the content in the conversation. `user`, `model`, `function`, or `tool` |
**Part object properties:**
| Property | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------- |
| `text` | string | no | Pure text content |
| `inlineData` | object | no | Inline media byte data |
| `fileData` | object | no | URI reference to the uploaded file |
| `functionCall` | object | no | Function call request |
| `functionResponse` | object | no | Function call response |
| `executableCode` | object | no | Executable code |
| `codeExecutionResult` | object | no | Code execution result |
**InlineData object properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------- |
| `mimeType` | string | yes | Media MIME type |
| `data` | string | yes | Base64 encoded media data |
**FileData object properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | -------------- |
| `mimeType` | string | yes | File MIME type |
| `fileUri` | string | yes | File URI |
#### `tools` [#tools]
* Type: array
* Required: no
A list of tools that the model might use to generate the next response. Supported tools include functions and code execution.
**Tool object properties:**
| Property | Type | Required | Description |
| ---------------------- | ------ | -------- | -------------------------------------- |
| `functionDeclarations` | array | no | Optional list of function declarations |
| `codeExecution` | object | no | Enable model to execute code |
**FunctionDeclaration object properties:**
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------ |
| `name` | string | yes | Function name |
| `description` | string | no | Function description |
| `parameters` | object | no | Function parameters, in JSON Schema format |
**FunctionCall object properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------- |
| `name` | string | yes | Name of the function to call |
| `args` | object | no | Key-value pairs of function arguments |
**FunctionResponse object properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------- |
| `name` | string | yes | Name of the called function |
| `response` | object | yes | Response data of the function call |
**ExecutableCode object properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------- |
| `language` | enum | yes | Programming language of the code |
| `code` | string | yes | Code to execute |
**CodeExecutionResult object properties:**
| Property | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `outcome` | enum | yes | Code execution result status |
| `output` | string | no | Output content of the code execution |
**CodeExecution object properties:**
| Property | Type | Required | Description |
| -------- | ------------ | -------- | --------------------------------------------------- |
| \{} | Empty object | - | Empty configuration object to enable code execution |
#### `toolConfig` [#toolconfig]
* Type: object
* Required: no
Tool configuration for any tools specified in the request.
**ToolConfig object properties:**
| Property | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------ |
| `functionCallingConfig` | object | no | Function calling configuration |
**FunctionCallingConfig object properties:**
| Property | Type | Required | Description |
| ---------------------- | ----- | -------- | ------------------------------------------- |
| `mode` | enum | no | Specifies the mode of function calling |
| `allowedFunctionNames` | array | no | List of function names allowed to be called |
**FunctionCallingMode enum values:**
* `MODE_UNSPECIFIED`: Default mode, model decides whether to call a function
* `AUTO`: Model automatically decides when to call a function
* `ANY`: Model must call a function
* `NONE`: Model cannot call a function
#### `safetySettings` [#safetysettings]
* Type: array
* Required: no
A list of SafetySetting instances to filter out unsafe content.
**SafetySetting object properties:**
| Property | Type | Required | Description |
| ----------- | ---- | -------- | ------------------ |
| `category` | enum | yes | Safety category |
| `threshold` | enum | yes | Blocking threshold |
**HarmCategory enum values:**
* `HARM_CATEGORY_HARASSMENT`: Harassment content
* `HARM_CATEGORY_HATE_SPEECH`: Hate speech and content
* `HARM_CATEGORY_SEXUALLY_EXPLICIT`: Explicitly sexual content
* `HARM_CATEGORY_DANGEROUS_CONTENT`: Dangerous content
* `HARM_CATEGORY_CIVIC_INTEGRITY`: Content that might be used to undermine civic integrity
**HarmBlockThreshold enum values:**
* `BLOCK_LOW_AND_ABOVE`: Allows content with a NEGLIGIBLE score to be published
* `BLOCK_MEDIUM_AND_ABOVE`: Allows content with a NEGLIGIBLE and LOW score to be published
* `BLOCK_ONLY_HIGH`: Allows content with a NEGLIGIBLE, LOW, and MEDIUM risk level to be published
* `BLOCK_NONE`: Allows all content
* `OFF`: Turns off safety filters
**Complete HarmBlockThreshold enum values:**
* `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: Threshold not specified
* `BLOCK_LOW_AND_ABOVE`: Blocks harmful content with a probability of medium or higher, only allowing NEGLIGIBLE level content
* `BLOCK_MEDIUM_AND_ABOVE`: Blocks harmful content with a probability of medium or higher, allowing NEGLIGIBLE and LOW level content
* `BLOCK_ONLY_HIGH`: Only blocks harmful content with a high probability, allowing NEGLIGIBLE, LOW, and MEDIUM level content
* `BLOCK_NONE`: Does not block any content, allowing all levels
* `OFF`: Completely turns off safety filters
#### `systemInstruction` [#systeminstruction]
* Type: object (Content)
* Required: no
System instruction set by the developer. Currently only supports text.
#### `generationConfig` [#generationconfig]
* Type: object
* Required: no
Model generation and output configuration options.
**GenerationConfig object properties:**
| Property | Type | Required | Description |
| ---------------------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `stopSequences` | array | no | Set of character sequences to stop generation (up to 5) |
| `responseMimeType` | string | no | MIME type of the generated candidate text |
| `responseSchema` | object | no | Output schema of the generated candidate text |
| `responseModalities` | array | no | Response modalities requested |
| `candidateCount` | integer | no | Number of generated answers to return |
| `maxOutputTokens` | integer | no | Maximum number of tokens in the candidate answers |
| `temperature` | number | no | Controls the randomness of output, range \[0.0, 2.0] |
| `topP` | number | no | Cumulative probability upper bound of tokens to consider during sampling |
| `topK` | integer | no | Maximum number of tokens to consider during sampling |
| `seed` | integer | no | Seed used for decoding |
| `presencePenalty` | number | no | Presence penalty |
| `frequencyPenalty` | number | no | Frequency penalty |
| `responseLogprobs` | boolean | no | Whether to export logprobs results in the response |
| `logprobs` | integer | no | Number of top logprobs returned |
| `enableEnhancedCivicAnswers` | boolean | no | Enables enhanced civic service answers |
| `speechConfig` | object | no | Speech generation configuration |
| `thinkingConfig` | object | no | Thinking function configuration |
| `mediaResolution` | enum | no | Specified media resolution |
**Supported MIME types:**
* `text/plain`: (default) Text output
* `application/json`: JSON response
* `text/x.enum`: ENUM as string response
**Modality enum values:**
* `TEXT`: Indicates model should return text
* `IMAGE`: Indicates model should return image
* `AUDIO`: Indicates model should return audio
**Schema object properties:**
| Property | Type | Required | Description |
| ------------- | ------- | -------- | -------------------------------------------------- |
| `type` | enum | yes | Data type |
| `description` | string | no | Field description |
| `enum` | array | no | List of enum values (when type is string) |
| `example` | any | no | Example value |
| `nullable` | boolean | no | Whether it can be null |
| `format` | string | no | String format (e.g., date, date-time) |
| `items` | object | no | Schema for array items (when type is array) |
| `properties` | object | no | Schema for object properties (when type is object) |
| `required` | array | no | List of required property names |
| `minimum` | number | no | Minimum value for numbers |
| `maximum` | number | no | Maximum value for numbers |
| `minItems` | integer | no | Minimum length for arrays |
| `maxItems` | integer | no | Maximum length for arrays |
| `minLength` | integer | no | Minimum length for strings |
| `maxLength` | integer | no | Maximum length for strings |
**Type enum values:**
* `TYPE_UNSPECIFIED`: Type not specified
* `STRING`: String type
* `NUMBER`: Number type
* `INTEGER`: Integer type
* `BOOLEAN`: Boolean type
* `ARRAY`: Array type
* `OBJECT`: Object type
**Supported programming languages (ExecutableCode):**
* `LANGUAGE_UNSPECIFIED`: Language not specified
* `PYTHON`: Python programming language
**Code execution result enum (Outcome):**
* `OUTCOME_UNSPECIFIED`: Result not specified
* `OUTCOME_OK`: Code execution successful
* `OUTCOME_FAILED`: Code execution failed
* `OUTCOME_DEADLINE_EXCEEDED`: Code execution timed out
#### `cachedContent` [#cachedcontent]
* Type: string
* Required: no
The name of cached content, used as context for providing predictions. Format: `cachedContents/{cachedContent}`
## 📥 Response [#-response]
### GenerateContentResponse [#generatecontentresponse]
Answer from models that support multiple candidate answers. The system reports safety ratings and content filtering for the prompt and each candidate.
#### `candidates` [#candidates]
* Type: array
* Description: List of candidate answers from the model
**Candidate object properties:**
| Property | Type | Description |
| ----------------------- | ------- | -------------------------------------------------------------------------- |
| `content` | object | Generated content returned by the model |
| `finishReason` | enum | Reason for the model to stop generating tokens |
| `safetyRatings` | array | List of safety ratings for the candidate answer |
| `citationMetadata` | object | Reference information for the generated candidate |
| `tokenCount` | integer | Token count for this candidate |
| `groundingAttributions` | array | Information about sources that contributed to generating a grounded answer |
| `groundingMetadata` | object | Reference metadata for the candidate object |
| `avgLogprobs` | number | Average log probability score for the candidate |
| `logprobsResult` | object | Log probability scores for answer tokens and preceding tokens |
| `urlRetrievalMetadata` | object | Metadata related to URL context retrieval tool |
| `urlContextMetadata` | object | Metadata related to URL context retrieval tool |
| `index` | integer | Index of the candidate in the response candidate list |
**FinishReason enum values:**
* `STOP`: Natural stopping point or provided stop sequence for the model
* `MAX_TOKENS`: Maximum token limit specified in the request reached
* `SAFETY`: Answer candidate content marked for safety reasons
* `RECITATION`: Answer candidate content marked for recitation reasons
* `LANGUAGE`: Answer candidate content marked for using unsupported language
* `OTHER`: Reason unknown
* `BLOCKLIST`: Token generation operation stopped because content contains prohibited words
* `PROHIBITED_CONTENT`: Token generation operation stopped because content might contain prohibited content
* `SPII`: Token generation operation stopped because content might contain sensitive personal information
* `MALFORMED_FUNCTION_CALL`: Model-generated function call invalid
* `IMAGE_SAFETY`: Token generation stopped because generated image violated safety rules
#### `promptFeedback` [#promptfeedback]
* Type: object
* Description: Prompt feedback related to content filtering
**PromptFeedback object properties:**
| Property | Type | Description |
| --------------- | ----- | ------------------------------ |
| `blockReason` | enum | Reason for blocking the prompt |
| `safetyRatings` | array | Safety rating for the prompt |
**BlockReason enum values:**
* `BLOCK_REASON_UNSPECIFIED`: Default value, this value is not used
* `SAFETY`: System blocked prompt due to safety reasons
* `OTHER`: Prompt blocked due to unknown reasons
* `BLOCKLIST`: System blocked this prompt because it contained terms in the blocklist
* `PROHIBITED_CONTENT`: System blocked this prompt because it contained prohibited content
* `IMAGE_SAFETY`: Candidate image blocked because it generated unsafe content
#### `usageMetadata` [#usagemetadata]
* Type: object
* Description: Metadata about token usage for the generation request
**UsageMetadata object properties:**
| Property | Type | Description |
| ---------------------------- | ------- | ---------------------------------------------------------------- |
| `promptTokenCount` | integer | Token count in the prompt |
| `cachedContentTokenCount` | integer | Token count in the cached part of the prompt |
| `candidatesTokenCount` | integer | Total token count in all generated candidate answers |
| `totalTokenCount` | integer | Total token count for the generation request |
| `toolUsePromptTokenCount` | integer | Token count in the prompt for tool usage |
| `thoughtsTokenCount` | integer | Token count for the thinking model's thoughts |
| `promptTokensDetails` | array | List of modalities processed in the request input |
| `candidatesTokensDetails` | array | List of modalities returned in the response |
| `cacheTokensDetails` | array | List of modalities in the cached content of the request input |
| `toolUsePromptTokensDetails` | array | List of modalities processed for tool usage in the request input |
#### `modelVersion` [#modelversion]
* Type: string
* Description: Model version used to generate the answer
#### `responseId` [#responseid]
* Type: string
* Description: ID for each response
#### Full response example [#full-response-example]
```json
{
"candidates": [
{
"content": {
"parts": [
{
"text": "你好！我是 Gemini，一个由 Google 开发的人工智能助手。我可以帮助您解答问题、提供信息、协助写作、代码编程等多种任务。请告诉我有什么可以为您效劳的！"
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE",
"blocked": false
}
],
"tokenCount": 47
}
],
"promptFeedback": {
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 47,
"totalTokenCount": 51,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 47
}
]
},
"modelVersion": "gemini-2.0-flash",
"responseId": "response-12345"
}
```
## 🔧 Advanced Features [#-advanced-features]
### Safety Ratings [#safety-ratings]
**SafetyRating object properties:**
| Property | Type | Description |
| ------------- | ------- | --------------------------------------------------- |
| `category` | enum | Category of this rating |
| `probability` | enum | Harmful probability for this content |
| `blocked` | boolean | Whether this content was blocked due to this rating |
**HarmProbability enum values:**
* `NEGLIGIBLE`: Harmful probability negligible
* `LOW`: Harmful probability low
* `MEDIUM`: Harmful probability medium
* `HIGH`: Harmful probability high
### Citation Metadata [#citation-metadata]
**CitationMetadata object properties:**
| Property | Type | Description |
| ----------------- | ----- | -------------------------------------- |
| `citationSources` | array | Source references for specific replies |
**CitationSource object properties:**
| Property | Type | Description |
| ------------ | ------- | --------------------------------------------------------------- |
| `startIndex` | integer | Start index of the response segment attributed to this source |
| `endIndex` | integer | End index of the attribution (exclusive) |
| `uri` | string | URI attributed to the text portion from this source |
| `license` | string | License of the GitHub project attributed to the source fragment |
### Code Execution [#code-execution]
When code execution tools are enabled, the model can generate and execute code to solve problems.
**Code execution example response:**
```json
{
"candidates": [
{
"content": {
"parts": [
{
"text": "我来计算斐波那契数列的第10项："
},
{
"executableCode": {
"language": "PYTHON",
"code": "def fibonacci(n):\n if n <= 1:\n return n\n else:\n return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'第10项斐波那契数是: {result}')"
}
},
{
"codeExecutionResult": {
"outcome": "OK",
"output": "第10项斐波那契数是: 55"
}
},
{
"text": "所以斐波那契数列的第10项是55。"
}
],
"role": "model"
},
"finishReason": "STOP"
}
]
}
```
### Grounding [#grounding]
**GroundingMetadata object properties:**
| Property | Type | Description |
| ------------------- | ------ | --------------------------------------------------------------------------------- |
| `groundingChunks` | array | List of supporting reference documents retrieved from specified grounding sources |
| `groundingSupports` | array | Grounding support list |
| `webSearchQueries` | array | Web search queries for subsequent web searches |
| `searchEntryPoint` | object | Google search entry point for subsequent web searches |
| `retrievalMetadata` | object | Metadata related to retrieval in the baseline process |
**GroundingAttribution object properties:**
| Property | Type | Description |
| ---------- | ------ | ------------------------------------------------------------- |
| `sourceId` | object | Identifier of the source that contributed to this attribution |
| `content` | object | Content of the source that contributed to this attribution |
**AttributionSourceId object properties:**
| Property | Type | Description |
| ------------------------ | ------ | ------------------------------------------------------- |
| `groundingPassage` | object | Identifier of the embedded paragraph |
| `semanticRetrieverChunk` | object | Identifier of the Chunk extracted by Semantic Retriever |
**GroundingPassageId object properties:**
| Property | Type | Description |
| ----------- | ------- | --------------------------------------------------------------------------- |
| `passageId` | string | ID of the paragraph matching GroundingPassage.id from GenerateAnswerRequest |
| `partIndex` | integer | Index of the part in GroundingPassage.content |
**SemanticRetrieverChunk object properties:**
| Property | Type | Description |
| -------- | ------ | -------------------------------------------------------------------- |
| `source` | string | Source name matching SemanticRetrieverConfig.source from the request |
| `chunk` | string | Name of the Chunk containing the attributed text |
**SearchEntryPoint object properties:**
| Property | Type | Description |
| ----------------- | ------ | -------------------------------------------------------------------------------- |
| `renderedContent` | string | Web content code segment embeddable in a webpage or app WebView |
| `sdkBlob` | string | Base64 encoded JSON, representing an array of search terms and search URL tuples |
**Segment object properties:**
| Property | Type | Description |
| ------------ | ------- | --------------------------------------------------------- |
| `partIndex` | integer | Index of the Part object within its parent Content object |
| `startIndex` | integer | Start index of the given part in bytes |
| `endIndex` | integer | End index of the given chunk in bytes |
| `text` | string | Text corresponding to the fragment in the response |
**RetrievalMetadata object properties:**
| Property | Type | Description |
| ----------------------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `googleSearchDynamicRetrievalScore` | number | Probability score of information from Google search helping to answer the question, range \[0,1] |
**GroundingChunk object properties:**
| Property | Type | Description |
| -------- | ------ | ---------------------------- |
| `web` | object | Grounding chunk from the web |
**Web object properties:**
| Property | Type | Description |
| -------- | ------ | --------------------------- |
| `uri` | string | URI reference for the chunk |
| `title` | string | Title of the data block |
**GroundingSupport object properties:**
| Property | Type | Description |
| ----------------------- | ------ | ---------------------------------------------------------------------- |
| `groundingChunkIndices` | array | List of indices, used to specify citations related to copyright claims |
| `confidenceScores` | array | Confidence scores for supporting reference documents, range 0-1 |
| `segment` | object | Content segment to which this support request belongs |
### Multimodal Processing [#multimodal-processing]
Gemini API supports processing multiple modalities of input and output:
**Supported input modalities:**
* `TEXT`: Pure text
* `IMAGE`: Images (JPEG, PNG, WebP, HEIC, HEIF)
* `AUDIO`: Audio (WAV, MP3, AIFF, AAC, OGG, FLAC)
* `VIDEO`: Videos (MP4, MPEG, MOV, AVI, FLV, MPG, WEBM, WMV, 3GPP)
* `DOCUMENT`: Documents (PDF)
**ModalityTokenCount object properties:**
| Property | Type | Description |
| ------------ | ------- | ----------------------------------------- |
| `modality` | enum | Modality associated with this token count |
| `tokenCount` | integer | Token count |
**MediaResolution enum values:**
* `MEDIA_RESOLUTION_LOW`: Low resolution (64 tokens)
* `MEDIA_RESOLUTION_MEDIUM`: Medium resolution (256 tokens)
* `MEDIA_RESOLUTION_HIGH`: High resolution (256 tokens for scaling and re-framing)
### Thinking Function [#thinking-function]
**ThinkingConfig object properties:**
| Property | Type | Description |
| ----------------- | ------- | ------------------------------------------------- |
| `includeThoughts` | boolean | Whether to include thinking content in the answer |
| `thinkingBudget` | integer | Number of idea tokens the model should generate |
### Speech Generation [#speech-generation]
**SpeechConfig object properties:**
| Property | Type | Description |
| ------------------------- | ------ | ---------------------------------------- |
| `voiceConfig` | object | Configuration for single voice output |
| `multiSpeakerVoiceConfig` | object | Configuration for multi-speaker settings |
| `languageCode` | string | Language code for speech synthesis |
**VoiceConfig object properties:**
| Property | Type | Description |
| --------------------- | ------ | ------------------------------------------- |
| `prebuiltVoiceConfig` | object | Configuration for the prebuilt voice to use |
**PrebuiltVoiceConfig object properties:**
| Property | Type | Description |
| ----------- | ------ | --------------------------------- |
| `voiceName` | string | Name of the prebuilt voice to use |
**MultiSpeakerVoiceConfig object properties:**
| Property | Type | Description |
| --------------------- | ----- | -------------------------- |
| `speakerVoiceConfigs` | array | All enabled speaker voices |
**SpeakerVoiceConfig object properties:**
| Property | Type | Description |
| ------------- | ------ | ---------------------------------- |
| `speaker` | string | Name of the speaker to use |
| `voiceConfig` | object | Configuration for the voice to use |
**Supported language codes:**
* `zh-CN`: Chinese (Simplified)
* `en-US`: English (US)
* `ja-JP`: Japanese
* `ko-KR`: Korean
* `fr-FR`: French
* `de-DE`: German
* `es-ES`: Spanish
* `pt-BR`: Portuguese (Brazil)
* `hi-IN`: Hindi
* `ar-XA`: Arabic
* `it-IT`: Italian
* `tr-TR`: Turkish
* `vi-VN`: Vietnamese
* `th-TH`: Thai
* `ru-RU`: Russian
* `pl-PL`: Polish
* `nl-NL`: Dutch
### Logprobs Results [#logprobs-results]
**LogprobsResult object properties:**
| Property | Type | Description |
| ------------------ | ----- | ------------------------------------------------------------------------------------------------- |
| `topCandidates` | array | Array of candidates sorted by log probability in descending order |
| `chosenCandidates` | array | Array of chosen candidates, not necessarily in topCandidates (length equals total decoding steps) |
**TopCandidates object properties:**
| Property | Type | Description |
| ------------ | ----- | -------------------------------------------------------- |
| `candidates` | array | Candidates sorted by log probability in descending order |
**Candidate (Logprobs) object properties:**
| Property | Type | Description |
| ---------------- | ------- | ------------------------------------ |
| `token` | string | Token string value for the candidate |
| `tokenId` | integer | Token ID value for the candidate |
| `logProbability` | number | Log probability for the candidate |
### URL Retrieval Function [#url-retrieval-function]
**UrlRetrievalMetadata object properties:**
| Property | Type | Description |
| ---------------------- | ----- | ------------------------------ |
| `urlRetrievalContexts` | array | List of URL retrieval contexts |
**UrlRetrievalContext object properties:**
| Property | Type | Description |
| -------------- | ------ | ------------------------- |
| `retrievedUrl` | string | URL retrieved by the tool |
**UrlContextMetadata object properties:**
| Property | Type | Description |
| ------------- | ----- | -------------------- |
| `urlMetadata` | array | List of URL contexts |
**UrlMetadata object properties:**
| Property | Type | Description |
| -------------------- | ------ | ------------------------- |
| `retrievedUrl` | string | URL retrieved by the tool |
| `urlRetrievalStatus` | enum | URL retrieval status |
**UrlRetrievalStatus enum values:**
* `URL_RETRIEVAL_STATUS_SUCCESS`: URL retrieval successful
* `URL_RETRIEVAL_STATUS_ERROR`: URL retrieval failed due to an error
### Complete Harm Categories [#complete-harm-categories]
**HarmCategory enum values:**
* `HARM_CATEGORY_UNSPECIFIED`: Category not specified
* `HARM_CATEGORY_DEROGATORY`: PaLM - Negative or harmful comments targeting identity and/or protected attributes
* `HARM_CATEGORY_TOXICITY`: PaLM - Rude, impolite, or profane content
* `HARM_CATEGORY_VIOLENCE`: PaLM - Scenarios depicting violence against individuals or groups
* `HARM_CATEGORY_SEXUAL`: PaLM - References to sexual behavior or other explicit content
* `HARM_CATEGORY_MEDICAL`: PaLM - Promoting unverified medical advice
* `HARM_CATEGORY_DANGEROUS`: PaLM - Dangerous content promotes, encourages, or facilitates harmful behavior
* `HARM_CATEGORY_HARASSMENT`: Gemini - Harassment content
* `HARM_CATEGORY_HATE_SPEECH`: Gemini - Hate speech and content
* `HARM_CATEGORY_SEXUALLY_EXPLICIT`: Gemini - Explicitly sexual content
* `HARM_CATEGORY_DANGEROUS_CONTENT`: Gemini - Dangerous content
* `HARM_CATEGORY_CIVIC_INTEGRITY`: Gemini - Content that might be used to undermine civic integrity
**HarmProbability enum values:**
* `HARM_PROBABILITY_UNSPECIFIED`: Probability not specified
* `NEGLIGIBLE`: Harmful probability negligible
* `LOW`: Harmful probability low
* `MEDIUM`: Harmful probability medium
* `HIGH`: Harmful probability high
**Modality enum values:**
* `MODALITY_UNSPECIFIED`: Modality not specified
* `TEXT`: Pure text
* `IMAGE`: Image
* `VIDEO`: Video
* `AUDIO`: Audio
* `DOCUMENT`: Document, e.g., PDF
**MediaResolution enum values:**
* `MEDIA_RESOLUTION_UNSPECIFIED`: Media resolution not set
* `MEDIA_RESOLUTION_LOW`: Media resolution set to low (64 tokens)
* `MEDIA_RESOLUTION_MEDIUM`: Media resolution set to medium (256 tokens)
* `MEDIA_RESOLUTION_HIGH`: Media resolution set to high (using 256 tokens for scaling and re-framing)
**UrlRetrievalStatus enum values:**
* `URL_RETRIEVAL_STATUS_UNSPECIFIED`: Default value, this value is not used
* `URL_RETRIEVAL_STATUS_SUCCESS`: URL retrieval successful
* `URL_RETRIEVAL_STATUS_ERROR`: URL retrieval failed due to an error
## 🔍 Error Handling [#-error-handling]
### Common Error Codes [#common-error-codes]
| Error Code | Description |
| ---------- | ----------------------------------------- |
| `400` | Request format error or invalid parameter |
| `401` | API key invalid or missing |
| `403` | Insufficient permissions or quota limit |
| `429` | Request frequency too high |
| `500` | Server internal error |
### Detailed Error Code Explanations [#detailed-error-code-explanations]
| Error Code | Status | Description | Solution |
| ---------- | --------------------- | ------------------------------------------------ | -------------------------------------------------- |
| `400` | `INVALID_ARGUMENT` | Request parameter invalid or format error | Check request parameter format and required fields |
| `400` | `FAILED_PRECONDITION` | Precondition for the request not met | Ensure API call prerequisites are met |
| `401` | `UNAUTHENTICATED` | API key invalid, missing, or expired | Check API key validity and format |
| `403` | `PERMISSION_DENIED` | Insufficient permissions or quota exhausted | Check API key permissions or upgrade quota |
| `404` | `NOT_FOUND` | Specified model or resource does not exist | Verify model name and resource path |
| `413` | `PAYLOAD_TOO_LARGE` | Request body too large | Reduce input content size or process in batches |
| `429` | `RESOURCE_EXHAUSTED` | Request frequency exceeded or quota insufficient | Reduce request frequency or wait for quota reset |
| `500` | `INTERNAL` | Server internal error | Retry the request, if persistent contact support |
| `503` | `UNAVAILABLE` | Service temporarily unavailable | Wait for a period and retry |
| `504` | `DEADLINE_EXCEEDED` | Request timed out | Reduce input size or retry the request |
### Error Response Example [#error-response-example]
```json
{
"error": {
"code": 400,
"message": "Invalid argument: contents",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "contents",
"description": "contents is required"
}
]
}
]
}
}
```
# Jina AI Rerank Format (/en/api/jinaai-rerank)
[Jina AI Rerank](https://jina.ai/reranker)
In ZipFlow, Jina AI's rerank format is adopted as the standard format. All other vendors' (such as Xinference, Cohere, etc.) rerank responses will be formatted to Jina AI's format to provide a unified development experience.
## 📝 Introduction [#-introduction]
Jina AI Rerank is a powerful text reranking model that can sort document lists by relevance based on queries. The model supports multiple languages and can process text content in different languages, assigning relevance scores to each document.
## 💡 Request Examples [#-request-examples]
### Basic Rerank Request ✅ [#basic-rerank-request-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "jina-reranker-v2-base-multilingual",
"query": "Organic skincare products for sensitive skin",
"top_n": 3,
"documents": [
"Organic skincare for sensitive skin with aloe vera and chamomile...",
"New makeup trends focus on bold colors and innovative techniques...",
"Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
]
}'
```
**Response Example:**
```json
{
"results": [
{
"document": {
"text": "Organic skincare for sensitive skin with aloe vera and chamomile..."
},
"index": 0,
"relevance_score": 0.8783142566680908
},
{
"document": {
"text": "Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
},
"index": 2,
"relevance_score": 0.7624675869941711
}
],
"usage": {
"prompt_tokens": 815,
"completion_tokens": 0,
"total_tokens": 815
}
}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/rerank
```
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### `model` [#model]
* Type: String
* Required: No
* Default: jina-reranker-v2-base-multilingual
* Description: The reranking model to use
#### `query` [#query]
* Type: String
* Required: Yes
* Description: Query text used to sort documents by relevance
#### `top_n` [#top_n]
* Type: Integer
* Required: No
* Default: No limit
* Description: Return the top N documents after sorting
#### `documents` [#documents]
* Type: Array of strings
* Required: Yes
* Description: List of documents to be reranked
* Limit: Each document's length should not exceed the model's maximum token limit
## 📥 Response [#-response]
### Successful Response [#successful-response]
#### `results` [#results]
* Type: Array
* Description: List of reranked documents
* Properties:
* `document`: Object containing document text
* `index`: Document's index in the original list
* `relevance_score`: Relevance score (between 0-1)
#### `usage` [#usage]
* Type: Object
* Description: Token usage statistics
* Properties:
* `prompt_tokens`: Number of tokens used for prompt
* `completion_tokens`: Number of tokens used for completion
* `total_tokens`: Total number of tokens
* `prompt_tokens_details`: Detailed prompt token information
* `cached_tokens`: Number of cached tokens
* `audio_tokens`: Number of audio tokens
* `completion_tokens_details`: Detailed completion token information
* `reasoning_tokens`: Number of reasoning tokens
* `audio_tokens`: Number of audio tokens
* `accepted_prediction_tokens`: Number of accepted prediction tokens
* `rejected_prediction_tokens`: Number of rejected prediction tokens
### Error Response [#error-response]
When there are issues with the request, the API will return an error response:
* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Invalid or missing API key
* `429 Too Many Requests`: Request frequency limit exceeded
* `500 Internal Server Error`: Internal server error
## 💡 Best Practices [#-best-practices]
### Query Optimization Suggestions [#query-optimization-suggestions]
1. Use clear and specific query text
2. Avoid overly broad or vague queries
3. Ensure the query uses the same language style as the documents
### Document Processing Suggestions [#document-processing-suggestions]
1. Keep document length moderate, don't exceed model limits
2. Ensure document content is complete and meaningful
3. Can include multilingual documents, the model supports cross-language matching
### Performance Optimization [#performance-optimization]
1. Reasonably set the top\_n parameter to reduce unnecessary calculations
2. For large numbers of documents, consider batch processing
3. Can cache results for common queries
### Multilingual Support [#multilingual-support]
This model supports document reranking in multiple languages, including but not limited to:
* English
* Chinese
* German
* Spanish
* Japanese
* French
No need to specify language parameters, the model will automatically identify and process content in different languages.
# Kling AI and Jimeng Formats (/en/api/kling-jimeng)
Call the video generation interface to generate videos, supporting multiple video generation services:
* **Kling AI**: [API Documentation](https://app.klingai.com/cn/dev/document-api/apiReference/commonInfo)
* **Jimeng**: [API Documentation](https://www.volcengine.com/docs/85621/1538636)
## Generate Video [#generate-video]
### API Endpoint [#api-endpoint]
```
POST /v1/video/generations
```
### Request Headers [#request-headers]
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------- |
| Authorization | string | Yes | User Authentication Token (Bearer: sk-xxxx) |
| Content-Type | string | Yes | application/json |
### Request Parameters [#request-parameters]
| Parameter | Type | Required | Description |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| model | string | Yes | Model/Style ID |
| prompt | string | Yes | Text Prompt |
| duration | number | No | Video Duration (seconds) |
| fps | integer | No | Video Frame Rate (FPS) |
| height | integer | No | Video Height |
| width | integer | No | Video Width |
| image | string | No | Image Input (URL/Base64) |
| metadata | object | No | Vendor Specific/Custom Parameters (e.g., negative\_prompt, style, quality\_level, etc.) |
| n | integer | No | Number of Videos to Generate |
| response\_format | string | No | Response Format |
| seed | integer | No | Random Seed |
| user | string | No | User Identifier |
### Request Examples [#request-examples]
#### Kling AI Example [#kling-ai-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-v1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"duration": 5,
"metadata": {
"seed": 20231234,
"negative_prompt": "模糊",
"image_tail": "https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png"
}
}'
```
#### Jimeng AI Example [#jimeng-ai-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "一个穿着宇航服的宇航员在月球上行走",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": [
"https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg"
],
"aspect_ratio": "16:9"
}
}'
```
#### Vidu Channel Example [#vidu-channel-example]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png",
"duration": 5,
"metadata": {
"duration": 5,
"seed": 0,
"resolution": "1080p",
"movement_amplitude": "auto",
"bgm": false,
"payload": "",
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
## Query Video [#query-video]
Query the status and results of the video generation task based on the Task ID
### API Endpoint [#api-endpoint-1]
```
GET /v1/video/generations/{task_id}
```
### Path Parameters [#path-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| task\_id | string | Yes | Task ID |
### Request Example [#request-example]
```bash
curl 'https://api.zipflow.xyz/v1/video/generations/{task_id}'
```
### Response Format [#response-format]
#### 200 - Successful Response [#200---successful-response]
```json
{
"error": null,
"format": "mp4",
"metadata": {
"duration": 5,
"fps": 30,
"height": 512,
"seed": 20231234,
"width": 512
},
"status": "succeeded",
"task_id": "abcd1234efgh",
"url": "string"
}
```
#### Response Field Description [#response-field-description]
| Field | Type | Description |
| -------- | ------ | ------------------------------------------- |
| task\_id | string | Task ID |
| status | string | Task Status (processing, succeeded, failed) |
| format | string | Video Format |
| url | string | Video Resource URL (on success) |
| metadata | object | Result Metadata |
| error | object | Error Information (null on success) |
## Error Responses [#error-responses]
### 400 - Request Parameter Error [#400---request-parameter-error]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - Unauthorized [#401---unauthorized]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - Forbidden [#403---forbidden]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 500 - Internal Server Error [#500---internal-server-error]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
# Midjourney Image Format (Midjourney Proxy/Midjourney Proxy Plus) (/en/api/midjourney-proxy-image)
This interface is **not an official Midjourney interface**, but rather a Midjourney proxy interface implemented based on the open-source project [**midjourney-proxy**](https://github.com/novicezk/midjourney-proxy) by author **novicezk**.
This project is divided into two versions, both of which ZipFlow has adapted:
* Open Source Version [midjourney-proxy](https://github.com/novicezk/midjourney-proxy)
* Paid Version [midjourney-proxy-plus](https://github.com/litter-coder/midjourney-proxy-plus)
We are very grateful for the author's contribution, which allows us to easily use Midjourney's powerful features. If you have time, please give the author a Star. If you have the ability, we recommend supporting the author's paid version, which supports more features.
| Feature Category | Open Source | Paid Version |
| ------------------------------------------ | ----------- | ------------ |
| **Basic Features** | | |
| Imagine commands and related actions | ✓ | ✓ |
| Image padding support | ✓ | ✓ |
| Blend (Image mixing) | ✓ | ✓ |
| Describe (Image to text) | ✓ | ✓ |
| Real-time task progress | ✓ | ✓ |
| Chinese prompt translation | ✓ | ✓ |
| Prompt sensitive word detection | ✓ | ✓ |
| User-token WSS connection | ✓ | ✓ |
| Multi-account configuration | ✓ | ✓ |
| **Advanced Features** | | |
| Shorten (Prompt analysis) | ✗ | ✓ |
| Focus movement (Pan) | ✗ | ✓ |
| Image zoom (Zoom) | ✗ | ✓ |
| Local redraw (Vary Region) | ✗ | ✓ |
| Associated button actions and Remix mode | ✗ | ✓ |
| Get image seed value | ✗ | ✓ |
| **Account Management** | | |
| Account pool persistence | ✗ | ✓ |
| Multiple storage support (Redis/MySQL) | ✗ | ✓ |
| Account information retrieval and settings | ✗ | ✓ |
| Task cancellation function | ✗ | ✓ |
| Built-in management backend | ✗ | ✓ |
| **Smart Features** | | |
| MJ V6.0 support | ✗ | ✓ |
| Automatic account status monitoring | ✗ | ✓ |
| Automatic mode switching | ✗ | ✓ |
| Niji・journey Bot support | ✗ | ✓ |
| InsightFace face service | ✗ | ✓ |
| **Security & Performance** | | |
| Dynamic configuration support | ✗ | ✓ |
| Token disconnection issue fixes | ✗ | ✓ |
| Automatic verification function | ✗ | ✓ |
| Prohibited word automatic appeal | ✗ | ✓ |
## 📝 Introduction [#-introduction]
Midjourney is a powerful image generation and processing model that can create, edit, and modify images based on natural language descriptions. By providing different interfaces, various image generation and processing tasks can be implemented.
## 🔄 Process Flow Diagram [#-process-flow-diagram]
```mermaid
graph TD
A[Start] --> B{Select Task Type}
%% Imagine Flow
B -->|Text to Image| C[Submit Imagine Task]
C --> D[Get Initial Image]
D --> E{Select Operation}
%% Basic Operation Branches
E -->|U1-U4| F[Upscale]
E -->|V1-V4| G[Variation]
%% Blend Flow
B -->|Image Mixing| H[Submit Blend Task]
H --> D
%% Describe Flow
B -->|Image to Text| I[Submit Describe Task]
I --> J[Get Image Description]
%% Action & Modal Flow
F --> K[Submit Action]
G --> K
K -->|Modal Required| L[Submit Modal]
K -->|Direct Execution| M[Execution Complete]
L --> M
%% Face Swap Flow
B -->|Face Replacement| N[Submit Swap Face Task]
N --> M
%% Query Related
M --> O{Subsequent Operations}
O -->|Query Progress| P[Get Task Details]
O -->|Get Seed| Q[Get Image Seed]
O -->|Save Image| R[Upload to Discord]
%% Style Definitions
classDef process fill:#f9f,stroke:#333,stroke-width:2px
classDef decision fill:#bbf,stroke:#333,stroke-width:2px
classDef endpoint fill:#bfb,stroke:#333,stroke-width:2px
class A,M,J,R endpoint
class B,E,O decision
class C,D,F,G,H,I,K,L,N,P,Q process
```
### Flow Description [#flow-description]
1. **Initial Tasks**
* Imagine: Text to image generation
* Blend: Multi-image mixing
* Describe: Image description
* Swap Face: Face replacement
2. **Image Processing**
* U1-U4: Upscale operations
* V1-V4: Variation generation
* Pan: Image translation
* Zoom: Image scaling
3. **Special Flows**
* Action + Modal: Operations requiring modal confirmation
* Direct Action execution: Operations not requiring modal
4. **Task Management**
* Get task details
* Get image seed
* Upload to Discord
## 💡 Request Examples [#-request-examples]
### Submit Imagine Task ✅ [#submit-imagine-task-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/imagine' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"prompt": "Cat",
"base64Array": [],
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**Response Example:**
```json
{
"code": 1,
"description": "Submitted successfully",
"properties": {},
"result": 1320098173412546
}
```
### Submit Blend Task ✅ [#submit-blend-task-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/blend' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"base64Array": [
"data:image/png;base64,xxx1",
"data:image/png;base64,xxx2"
],
"dimensions": "SQUARE",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**Response Example:**
```json
{
"code": 1,
"description": "Submitted successfully",
"properties": {},
"result": 1320098173412546
}
```
### Submit Describe Task ✅ [#submit-describe-task-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/describe' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"base64": "data:image/png;base64,xxx",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**Response Example:**
```json
{
"code": 1,
"description": "Submitted successfully",
"properties": {},
"result": 1320098173412546
}
```
### Submit Modal ✅ [#submit-modal-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/modal' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"maskBase64": "",
"prompt": "",
"taskId": "14001934816969359"
}'
```
**Response Example:**
```json
{
"code": 1,
"description": "Submitted successfully",
"properties": {},
"result": 1320098173412546
}
```
### Submit swap\_face Task ✅ [#submit-swap_face-task-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/insight-face/swap' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"sourceBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RDnYdriP1wsS81kwU8OVs/R3xu8s6bX7+zYnOH8coSqpmRSBjqerjcBlr2OB/lbAf/2Q==",
"targetBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD849k="
}'
```
**Response Example:**
```json
{
"code": 0,
"description": "string",
"result": "string"
}
```
### Execute Action ✅ [#execute-action-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/action' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"chooseSameChannel": true,
"customId": "MJ::JOB::upsample::1::82c51c9d-bc33-4c07-a471-36c3dcb1a6f0",
"taskId": "1728781324658687",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**Response Example:**
```json
{
"code": 1,
"description": "Submitted successfully",
"properties": {},
"result": 1320098173412546
}
```
### Upload Files to Discord ✅ [#upload-files-to-discord-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/upload-discord-images' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"base64Array": [],
"filter": {
"channelId": "",
"instanceId": "",
"remark": ""
}
}'
```
**Response Example:**
```json
{
"code": 0,
"description": "string",
"result": [
"string"
]
}
```
### Query Tasks by ID List ✅ [#query-tasks-by-id-list-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/task/list-by-condition' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"ids": []
}'
```
**Response Example:**
```json
[
{
"action": "IMAGINE",
"buttons": [
{
"customId": "string",
"emoji": "string",
"label": "string",
"style": 0,
"type": 0
}
],
"description": "string",
"failReason": "string",
"finishTime": 0,
"id": "string",
"imageUrl": "string",
"progress": "string",
"prompt": "string",
"promptEn": "string",
"properties": {},
"startTime": 0,
"state": "string",
"status": "NOT_START",
"submitTime": 0
}
]
```
### Get Task by Specific ID ✅ [#get-task-by-specific-id-]
```bash
curl --location --request GET 'https://api.zipflow.xyz/mj/task/{id}/fetch' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json'
```
**Response Example:**
```json
{
"action": "IMAGINE",
"buttons": [
{
"customId": "string",
"emoji": "string",
"label": "string",
"style": 0,
"type": 0
}
],
"description": "string",
"failReason": "string",
"finishTime": 0,
"id": "string",
"imageUrl": "string",
"progress": "string",
"prompt": "string",
"promptEn": "string",
"properties": {},
"startTime": 0,
"state": "string",
"status": "NOT_START",
"submitTime": 0
}
```
### Get Task Image Seed ✅ [#get-task-image-seed-]
```bash
curl --location --request GET 'https://api.zipflow.xyz/mj/task/{id}/image-seed' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json'
```
**Response Example:**
```json
{
"code": 0,
"description": "string",
"result": "string"
}
```
## 📮 Request [#-request]
### Endpoints [#endpoints]
#### Submit Imagine Task [#submit-imagine-task]
```
POST /mj/submit/imagine
```
Create images based on text prompts.
#### Submit Blend Task [#submit-blend-task]
```
POST /mj/submit/blend
```
Generate new images by blending multiple input images.
#### Submit Describe Task [#submit-describe-task]
```
POST /mj/submit/describe
```
Generate text descriptions based on input images.
#### Submit Modal [#submit-modal]
```
POST /mj/submit/modal
```
Submit modal information for adjusting image generation details.
#### Submit swap\_face Task [#submit-swap_face-task]
```
POST /mj/insight-face/swap
```
Perform face swapping based on source and target images.
#### Execute Action [#execute-action]
```
POST /mj/submit/action
```
Perform subsequent operations on generated images, such as upscaling, adjustments, etc.
#### Upload Files to Discord [#upload-files-to-discord]
```
POST /mj/submit/upload-discord-images
```
Upload images to the Discord platform.
#### Query Tasks by ID List [#query-tasks-by-id-list]
```
POST /mj/task/list-by-condition
```
Query task details based on specified task ID list.
#### Get Task by Specific ID [#get-task-by-specific-id]
```
GET /mj/task/{id}/fetch
```
Get task details by task ID.
#### Get Task Image Seed [#get-task-image-seed]
```
GET /mj/task/{id}/image-seed
```
Get the seed value of the image generated by the specified task.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### Submit Imagine Task [#submit-imagine-task-1]
##### `botType` [#bottype]
* Type: Enum string
* Required: No
* Default: MID\_JOURNEY
* Options:
* `MID_JOURNEY`: Midjourney model
* `NIJI_JOURNEY`: Niji Journey model
* Description: Select the bot type to use
##### `prompt` [#prompt]
* Type: String
* Required: Yes
* Description: Text prompt for image generation
* Tips:
* Use clear and specific descriptions
* Can include artistic style, composition, and other details
* Supports both English and Chinese input
##### `base64Array` [#base64array]
* Type: String array
* Required: No
* Description: Base64 encoded array for image padding
* Format: Each element should be a complete base64 image string with MIME type prefix
##### `accountFilter` [#accountfilter]
* Type: Object
* Required: No
* Properties:
* `channelId`: Channel ID
* `instanceId`: Account instance ID
* `modes`: Account mode array, options: RELAX, FAST, TURBO
* `remark`: Content included in remarks
* `remix`: Whether the account supports remix
* `remixAutoConsidered`: Remix auto-submit settings
##### `notifyHook` [#notifyhook]
* Type: String
* Required: No
* Description: Callback address after task completion, uses global notifyHook when empty
##### `state` [#state]
* Type: String
* Required: No
* Description: Custom state parameter for tracking requests
#### Submit Blend Task [#submit-blend-task-1]
##### `base64Array` [#base64array-1]
* Type: String array
* Required: Yes
* Description: Base64 encoded array of images to blend
* Format: Must include 2-5 base64 image strings
##### `dimensions` [#dimensions]
* Type: Enum string
* Required: No
* Options:
* `PORTRAIT`: 2:3 ratio
* `SQUARE`: 1:1 ratio
* `LANDSCAPE`: 3:2 ratio
* Description: Output image aspect ratio settings
#### Submit Describe Task [#submit-describe-task-1]
##### `base64` [#base64]
* Type: String
* Required: Yes
* Description: Base64 encoding of the image to be described
* Format: Complete base64 string with MIME type prefix
#### Submit Modal Task [#submit-modal-task]
##### `maskBase64` [#maskbase64]
* Type: String
* Required: No
* Description: Base64 encoding of the mask image for local redraw
##### `prompt` [#prompt-1]
* Type: String
* Required: No
* Description: Text prompt for the redraw area
##### `taskId` [#taskid]
* Type: String
* Required: Yes
* Description: ID of the original task
#### Submit Swap Face Task [#submit-swap-face-task]
##### `sourceBase64` [#sourcebase64]
* Type: String
* Required: Yes
* Description: Base64 encoding of the face source image
* Requirements: Image must contain a clear face
##### `targetBase64` [#targetbase64]
* Type: String
* Required: Yes
* Description: Base64 encoding of the target image
* Requirements: Image must contain the face to be replaced
#### Execute Action [#execute-action-1]
##### `chooseSameChannel` [#choosesamechannel]
* Type: Boolean
* Required: No
* Default: false
* Description: Whether to select accounts in the same channel
##### `customId` [#customid]
* Type: String
* Required: Yes
* Description: Action identifier
* Format: Specific format string, such as "MJ::JOB::upsample::1::xxx"
##### `taskId` [#taskid-1]
* Type: String
* Required: Yes
* Description: Task ID for the action to be executed
#### Upload Files to Discord [#upload-files-to-discord-1]
##### `base64Array` [#base64array-2]
* Type: String array
* Required: Yes
* Description: Base64 encoded array of images to upload
##### `filter` [#filter]
* Type: Object
* Required: No
* Properties:
* `channelId`: Target channel ID
* `instanceId`: Account instance ID
* `remark`: Remark information
#### Query Tasks by ID List [#query-tasks-by-id-list-1]
##### `ids` [#ids]
* Type: String array
* Required: Yes
* Description: List of task IDs to query
### Common Response Format [#common-response-format]
All interfaces return similar response structures:
##### `code` [#code]
* Type: Integer
* Description: Status code
| Status Code | Description |
| ----------- | ---------------------- |
| 1 | Submitted successfully |
| 22 | Task queued |
| 21 | Parameter error |
| 23 | System error |
| 24 | Account unavailable |
| 25 | Insufficient balance |
##### `description` [#description]
* Type: String
* Description: Response description information
##### `properties` [#properties]
* Type: Object
* Description: Extended properties
##### `result` [#result]
* Type: String or array
* Description: Return result, may be task ID or other data
## 📥 Response [#-response]
### Successful Response [#successful-response]
#### `action` [#action]
* Type: Enum string
* Description: Task type
| String Value | Description |
| ------------ | ------------------ |
| `IMAGINE` | Create image |
| `UPSCALE` | Upscale image |
| `VARIATION` | Generate variation |
| `ZOOM` | Zoom image |
| `PAN` | Pan image |
| `DESCRIBE` | Image description |
| `BLEND` | Image blending |
| `SHORTEN` | Shorten prompt |
| `SWAP_FACE` | Face replacement |
#### `buttons` [#buttons]
* Type: Object array
* Description: Executable operation buttons
| Array Properties | Description |
| ---------------- | ---------------------------------- |
| `customId` | Action identifier |
| `emoji` | Button icon |
| `label` | Button text |
| `style` | Style (2=Primary, 3=Green) |
| `type` | Type used internally by the system |
#### `description` [#description-1]
* Type: String
* Description: Task description information
#### `failReason` [#failreason]
* Type: String
* Description: Task failure reason
#### `finishTime` [#finishtime]
* Type: Integer
* Description: Task completion timestamp
#### `id` [#id]
* Type: String
* Description: Task unique identifier
#### `imageUrl` [#imageurl]
* Type: String
* Description: URL of the generated image
#### `progress` [#progress]
* Type: String
* Description: Task progress information
#### `prompt` [#prompt-2]
* Type: String
* Description: Original prompt
#### `promptEn` [#prompten]
* Type: String
* Description: English prompt
#### `status` [#status]
* Type: Enum string
* Description: Task status
| String Value | Description |
| ------------- | --------------------------- |
| `NOT_START` | Not started |
| `SUBMITTED` | Submitted |
| `MODAL` | Modal operation in progress |
| `IN_PROGRESS` | In progress |
| `FAILURE` | Failed |
| `SUCCESS` | Successful |
| `CANCEL` | Cancelled |
#### `submitTime` [#submittime]
* Type: Integer
* Description: Task submission timestamp
#### `startTime` [#starttime]
* Type: Integer
* Description: Task execution start timestamp
### Error Response [#error-response]
When there are issues with the request, the API will return an error response:
#### HTTP Status Codes [#http-status-codes]
* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Invalid or missing API key
* `403 Forbidden`: Insufficient permissions
* `404 Not Found`: Resource not found
* `429 Too Many Requests`: Request frequency limit exceeded
* `500 Internal Server Error`: Internal server error
#### Error Response Format [#error-response-format]
```json
{
"code": ,
"description": "Error description information",
"result": null
}
```
## 💡 Best Practices [#-best-practices]
### Prompt Writing Suggestions [#prompt-writing-suggestions]
1. Use clear and concise language to describe the expected image content
2. Can refer to various parameters supported by Midjourney to control image style
3. Appropriately use negative descriptions to exclude unwanted elements
4. Can use image URLs as references to guide generation
### Image Generation Process [#image-generation-process]
1. Submit Imagine task to get initial images
2. Further optimize through Blend, Modal, and other tasks as needed
3. Execute Action operations for image fine-tuning
4. Upload and save satisfactory result images
### Image Format Requirements [#image-format-requirements]
1. Supported image formats:
* JPEG/JPG
* PNG
* GIF (static)
* WEBP
2. Image size limitations:
* File size: Maximum 4MB
* Resolution: Recommended 1024x1024 or higher
* Aspect ratio: Supports 1:1, 2:3, 3:2
### Performance Optimization Suggestions [#performance-optimization-suggestions]
1. Base64 encoding:
* Use standard Base64 encoding format
* Include correct MIME type prefix
* Compress images to reduce data transmission
2. Task processing:
* Use webhook to receive task completion notifications
* Set reasonable retry strategies
* Recommend using asynchronous processing methods
### Error Handling [#error-handling]
* Implement request retry mechanisms
* Add error log recording
* Set reasonable timeout times
# OpenAI Audio Format (/en/api/openai-audio)
[OpenAI Audio](https://platform.openai.com/docs/api-reference/audio)
## 📝 Introduction [#-introduction]
OpenAI Audio API provides three main functions:
1. Text-to-Speech (TTS) - Convert text to natural speech
2. Speech-to-Text (STT) - Transcribe audio to text
3. Audio Translation - Translate non-English audio to English text
## 💡 Request Examples [#-request-examples]
### Text-to-Speech ✅ [#text-to-speech-]
```bash
curl https://api.zipflow.xyz/v1/audio/speech \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"input": "Hello, world!",
"voice": "alloy"
}' \
--output speech.mp3
```
### Speech-to-Text ✅ [#speech-to-text-]
```bash
curl https://api.zipflow.xyz/v1/audio/transcriptions \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/audio.mp3" \
-F model="whisper-1"
```
**Response Example:**
```json
{
"text": "Hello, world!"
}
```
### Audio Translation ✅ [#audio-translation-]
```bash
curl https://api.zipflow.xyz/v1/audio/translations \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/chinese.mp3" \
-F model="whisper-1"
```
**Response Example:**
```json
{
"text": "Hello, world!"
}
```
## 📮 Request [#-request]
### Endpoints [#endpoints]
#### Text-to-Speech [#text-to-speech]
```
POST /v1/audio/speech
```
Convert text to speech.
#### Speech-to-Text [#speech-to-text]
```
POST /v1/audio/transcriptions
```
Transcribe audio to text in the input language.
#### Audio Translation [#audio-translation]
```
POST /v1/audio/translations
```
Translate audio to English text.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### Text-to-Speech [#text-to-speech-1]
##### `model` [#model]
* Type: String
* Required: Yes
* Optional values: tts-1, tts-1-hd
* Description: TTS model to use
##### `input` [#input]
* Type: String
* Required: Yes
* Maximum length: 4096 characters
* Description: Text to convert to speech
##### `voice` [#voice]
* Type: String
* Required: Yes
* Optional values: alloy, echo, fable, onyx, nova, shimmer
* Description: Voice to use when generating speech
##### `response_format` [#response_format]
* Type: String
* Required: No
* Default: mp3
* Optional values: mp3, opus, aac, flac, wav, pcm
* Description: Audio output format
##### `speed` [#speed]
* Type: Number
* Required: No
* Default: 1.0
* Range: 0.25 - 4.0
* Description: Speed of generated speech
#### Speech-to-Text [#speech-to-text-1]
##### `file` [#file]
* Type: File
* Required: Yes
* Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* Description: Audio file to transcribe
##### `model` [#model-1]
* Type: String
* Required: Yes
* Currently only supports: whisper-1
* Description: Model ID to use
##### `language` [#language]
* Type: String
* Required: No
* Format: ISO-639-1 (e.g., "en")
* Description: Language of the audio, providing this can improve accuracy
##### `prompt` [#prompt]
* Type: String
* Required: No
* Description: Text to guide the model's style or continue from a previous audio segment
##### `response_format` [#response_format-1]
* Type: String
* Required: No
* Default: json
* Optional values: json, text, srt, verbose\_json, vtt
* Description: Output format
##### `temperature` [#temperature]
* Type: Number
* Required: No
* Default: 0
* Range: 0 - 1
* Description: Sampling temperature, higher values make output more random
##### `timestamp_granularities` [#timestamp_granularities]
* Type: Array
* Required: No
* Default: segment
* Optional values: word, segment
* Description: Granularity of transcription timestamps
#### Audio Translation [#audio-translation-1]
##### `file` [#file-1]
* Type: File
* Required: Yes
* Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* Description: Audio file to translate
##### `model` [#model-2]
* Type: String
* Required: Yes
* Currently only supports: whisper-1
* Description: Model ID to use
##### `prompt` [#prompt-1]
* Type: String
* Required: No
* Description: English text to guide the model's style
##### `response_format` [#response_format-2]
* Type: String
* Required: No
* Default: json
* Optional values: json, text, srt, verbose\_json, vtt
* Description: Output format
##### `temperature` [#temperature-1]
* Type: Number
* Required: No
* Default: 0
* Range: 0 - 1
* Description: Sampling temperature, higher values make output more random
## 📥 Response [#-response]
### Successful Response [#successful-response]
#### Text-to-Speech [#text-to-speech-2]
Returns binary audio file content.
#### Speech-to-Text [#speech-to-text-2]
##### Basic JSON Format [#basic-json-format]
```json
{
"text": "Transcribed text content"
}
```
##### Detailed JSON Format [#detailed-json-format]
```json
{
"task": "transcribe",
"language": "english",
"duration": 8.47,
"text": "Complete transcribed text",
"segments": [
{
"id": 0,
"seek": 0,
"start": 0.0,
"end": 3.32,
"text": "Segmented transcribed text",
"tokens": [50364, 440, 7534],
"temperature": 0.0,
"avg_logprob": -0.286,
"compression_ratio": 1.236,
"no_speech_prob": 0.009
}
]
}
```
#### Audio Translation [#audio-translation-2]
```json
{
"text": "Translated English text"
}
```
### Error Response [#error-response]
When a request encounters an issue, the API will return an error response object, with HTTP status codes in the 4XX-5XX range.
#### Common Error Status Codes [#common-error-status-codes]
* `400 Bad Request`: Invalid request parameters
* `401 Unauthorized`: Invalid API key or not provided
* `429 Too Many Requests`: Exceeded API call limit
* `500 Internal Server Error`: Server internal error
Error response example:
```json
{
"error": {
"message": "Unsupported file format",
"type": "invalid_request_error",
"param": "file",
"code": "invalid_file_format"
}
}
```
# OpenAI Chat Format (Chat Completions) (/en/api/openai-chat)
[OpenAI Chat](https://platform.openai.com/docs/api-reference/chat)
## 📝 Introduction [#-introduction]
Given a list of messages comprising a conversation, the model will return a response. For related guidelines, please refer to the OpenAI official website: [Chat Completions](https://platform.openai.com/docs/guides/chat)
## 💡 Request Examples [#-request-examples]
### Basic Text Chat ✅ [#basic-text-chat-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
]
}'
```
**Response Example:**
```json
{
"id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
"object": "chat.completion",
"created": 1741569952,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you?",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 19,
"completion_tokens": 10,
"total_tokens": 29,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default"
}
```
### Image Analysis Chat ✅ [#image-analysis-chat-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
}
]
}
],
"max_tokens": 300
}'
```
**Response Example:**
```json
{
"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
"object": "chat.completion",
"created": 1741570283,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The image shows a wooden boardwalk path through dense green grass or meadow. The sky is bright blue with scattered clouds, creating a peaceful and serene atmosphere for the entire scene. Trees and shrubs can be seen in the background.",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1117,
"completion_tokens": 46,
"total_tokens": 1163,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default",
"system_fingerprint": "fp_fc9f1d7035"
}
```
### Streaming Response ✅ [#streaming-response-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello!"
}
],
"stream": true
}'
```
**Streaming Response Example:**
```jsonl
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]}
// ... more data chunks ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}
```
### Function Calling ✅ [#function-calling-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": "What's the weather like in Boston today?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "Get the current weather for a specified location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and state, e.g., San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
}
],
"tool_choice": "auto"
}'
```
**Response Example:**
```json
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1699896916,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\n\"location\": \"Boston, MA\"\n}"
}
}
]
},
"logprobs": null,
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 82,
"completion_tokens": 17,
"total_tokens": 99,
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
}
}
```
### Logprobs Request ✅ [#logprobs-request-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": "Hello!"
}
],
"logprobs": true,
"top_logprobs": 2
}'
```
**Response Example:**
```json
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1702685778,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you?"
},
"logprobs": {
"content": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111],
"top_logprobs": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111]
},
{
"token": "Hi",
"logprob": -1.3190403,
"bytes": [72, 105]
}
]
},
{
"token": "!",
"logprob": -0.02380986,
"bytes": [
33
],
"top_logprobs": [
{
"token": "!",
"logprob": -0.02380986,
"bytes": [33]
},
{
"token": " there",
"logprob": -3.787621,
"bytes": [32, 116, 104, 101, 114, 101]
}
]
},
{
"token": " How",
"logprob": -0.000054669687,
"bytes": [32, 72, 111, 119],
"top_logprobs": [
{
"token": " How",
"logprob": -0.000054669687,
"bytes": [32, 72, 111, 119]
},
{
"token": "<|end|>",
"logprob": -10.953937,
"bytes": null
}
]
},
{
"token": " can",
"logprob": -0.015801601,
"bytes": [32, 99, 97, 110],
"top_logprobs": [
{
"token": " can",
"logprob": -0.015801601,
"bytes": [32, 99, 97, 110]
},
{
"token": " may",
"logprob": -4.161023,
"bytes": [32, 109, 97, 121]
}
]
},
{
"token": " I",
"logprob": -3.7697225e-6,
"bytes": [
32,
73
],
"top_logprobs": [
{
"token": " I",
"logprob": -3.7697225e-6,
"bytes": [32, 73]
},
{
"token": " assist",
"logprob": -13.596657,
"bytes": [32, 97, 115, 115, 105, 115, 116]
}
]
},
{
"token": " assist",
"logprob": -0.04571125,
"bytes": [32, 97, 115, 115, 105, 115, 116],
"top_logprobs": [
{
"token": " assist",
"logprob": -0.04571125,
"bytes": [32, 97, 115, 115, 105, 115, 116]
},
{
"token": " help",
"logprob": -3.1089056,
"bytes": [32, 104, 101, 108, 112]
}
]
},
{
"token": " you",
"logprob": -5.4385737e-6,
"bytes": [32, 121, 111, 117],
"top_logprobs": [
{
"token": " you",
"logprob": -5.4385737e-6,
"bytes": [32, 121, 111, 117]
},
{
"token": " today",
"logprob": -12.807695,
"bytes": [32, 116, 111, 100, 97, 121]
}
]
},
{
"token": " today",
"logprob": -0.0040071653,
"bytes": [32, 116, 111, 100, 97, 121],
"top_logprobs": [
{
"token": " today",
"logprob": -0.0040071653,
"bytes": [32, 116, 111, 100, 97, 121]
},
{
"token": "?",
"logprob": -5.5247097,
"bytes": [63]
}
]
},
{
"token": "?",
"logprob": -0.0008108172,
"bytes": [63],
"top_logprobs": [
{
"token": "?",
"logprob": -0.0008108172,
"bytes": [63]
},
{
"token": "?\n",
"logprob": -7.184561,
"bytes": [63, 10]
}
]
}
]
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 9,
"total_tokens": 18,
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": null
}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/chat/completions
```
Create a model response for a given chat conversation. For more details, please refer to the text generation, visual, and audio guides.
### Authentication Method [#authentication-method]
Include the following in the request headers for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key. You can find or generate your API key on the API keys page of the OpenAI platform.
### Request Body Parameters [#request-body-parameters]
#### `messages` [#messages]
* Type: Array
* Required: Yes
The list of messages comprising the conversation so far. Depending on the model used, different message types (forms) are supported, such as text, image, and audio.
| Message Type | Description |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Developer message** | Developer instructions, the model should follow these instructions regardless of what message the user sends. In o1 models and newer versions, developer messages replace previous system messages. |
| **System message** | Developer instructions, the model should follow these instructions regardless of what message the user sends. In o1 models and newer versions, please use developer messages instead. |
| **User message** | Messages sent by the terminal user, containing prompts or additional context information. |
| **Assistant message** | Messages sent by the model in response to user messages. |
| **Tool message** | Content of a tool message. |
| **Function message** | Deprecated. |
**Developer message Properties:**
| Property | Type | Required | Description |
| --------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `role` | String | Yes | The role of the message author, here "developer". |
| `content` | String or Array | Yes | The content of the developer message. Can be text content (string) or an array of content parts. |
| `name` | String | No | An optional name for the participant. Provides information to the model to distinguish between participants with the same role. |
**System message Properties:**
| Property | Type | Required | Description |
| --------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `role` | String | Yes | The role of the message author, here "system". |
| `content` | String or Array | Yes | The content of the system message. Can be text content (string) or an array of content parts. |
| `name` | String | No | An optional name for the participant. Provides information to the model to distinguish between participants with the same role. |
**User message Properties:**
| Property | Type | Required | Description |
| --------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `role` | String | Yes | The role of the message author, here "user". |
| `content` | String or Array | Yes | The content of the user message. Can be text content (string) or an array of content parts. |
| `name` | String | No | An optional name for the participant. Provides information to the model to distinguish between participants with the same role. |
**Content Part Types:**
| Content Part Type | Description | Can Be Used For |
| ------------------------ | ------------------------------------------ | ------------------ |
| **Text Content Part** | Text input. | All message types |
| **Image Content Part** | Image input. | User messages |
| **Audio Content Part** | Audio input. | User messages |
| **File Content Part** | File input, used for text generation. | User messages |
| **Refusal Content Part** | Rejection messages generated by the model. | Assistant messages |
**Text Content Part Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------- |
| `text` | String | Yes | Text content. |
| `type` | String | Yes | The type of content part. |
**Image Content Part Properties:**
| Property | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------- |
| `image_url` | Object | Yes | Contains an image URL or base64 encoded image data. |
| `type` | String | Yes | The type of content part. |
**Image URL Object Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| `url` | String | Yes | The URL of the image or base64 encoded image data. |
| `detail` | String | No | Specifies the detailed level of the image. Defaults to "auto". |
**Audio Content Part Properties:**
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------ |
| `input_audio` | Object | Yes | Contains an object with audio data. |
| `type` | String | Yes | The type of content part. Always "input\_audio". |
**Audio Input Object Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------- |
| `data` | String | Yes | Base64 encoded audio data. |
| `format` | String | Yes | The format of the encoded audio data. Currently supports "wav" and "mp3". |
**File Content Part Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------- |
| `file` | Object | Yes | Contains an object with file data. |
| `type` | String | Yes | The type of content part. Always "file". |
**File Object Properties:**
| Property | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------------------------------- |
| `file_data` | String | No | Base64 encoded file data, used to pass the file as a string to the model. |
| `file_id` | String | No | The ID of the uploaded file, used as input. |
| `filename` | String | No | The filename, used to pass the file as a string to the model. |
**Assistant message Properties:**
| Property | Type | Required | Description |
| --------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `role` | String | Yes | The role of the message author, here "assistant". |
| `content` | String or Array | No | The content of the assistant message. Required unless `tool_calls` or `function_call` is specified. |
| `name` | String | No | An optional name for the participant. Provides information to the model to distinguish between participants with the same role. |
| `audio` | Object or null | No | Data about the model's previous audio response. |
| `function_call` | Object or null | No | Deprecated, replaced by `tool_calls`. The name and parameters of the function to be called, generated by the model. |
| `tool_calls` | Array | No | Tool calls generated by the model, such as function calls. |
| `refusal` | String or null | No | The assistant's refusal message. |
**Tool message Properties:**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------------------------- |
| `role` | String | Yes | The role of the message author, here "tool". |
| `content` | String or Array | Yes | The content of the tool message. |
| `tool_call_id` | String | Yes | The tool call associated with this message response. |
**Function message Properties (Deprecated):**
| Property | Type | Required | Description |
| --------- | -------------- | -------- | ------------------------------------------------ |
| `role` | String | Yes | The role of the message author, here "function". |
| `content` | String or null | Yes | The content of the function message. |
| `name` | String | Yes | The name of the function to be called. |
#### `model` [#model]
* Type: String
* Required: Yes
The ID of the model to use. For details on which models are compatible with the Chat API, please refer to the model endpoint compatibility table.
#### `store` [#store]
* Type: Boolean or null
* Required: No
* Default: false
Whether to store the output of this chat completion request for our model distillation or evaluation products.
#### `reasoning_effort` [#reasoning_effort]
* Type: String or null
* Required: No
* Default: medium
* Only applicable to o-series models
Constraints the reasoning effort of the reasoning model. Current supported values are `low`, `medium`, and `high`. Reducing reasoning effort can speed up responses and reduce the number of tokens used for reasoning in the response.
#### `metadata` [#metadata]
* Type: map
* Required: No
A collection of 16 key-value pairs that can be attached to the object. This is useful for storing other information about the object in a structured format and querying the object via API or the dashboard.
Keys are strings of maximum length 64 characters. Values are strings of maximum length 512 characters.
#### `modalities` [#modalities]
* Type: Array or null
* Required: No
The types of output you want the model to generate for this request. Most models can generate text, which is the default:
\["text"]
The model can also be used to generate audio. To request that the model generate both text and audio responses simultaneously, you can use:
\["text", "audio"]
#### `prediction` [#prediction]
* Type: Object
* Required: No
Configuration for the predicted output, when you know most of the content of the model response in advance, it can greatly improve response time. This is most common when you are only making small changes to a file.
**Possible Types:**
| Type | Description |
| ------------------ | --------------------------------------------------------------------------------------------------- |
| **Static Content** | Static predicted output content, e.g., text content of a file with small changes being regenerated. |
**Static Content Properties:**
| Property | Type | Required | Description |
| --------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `content` | String or Array | Yes | The content that should be matched when generating the model response. If the generated tokens match this content, the entire model response can return faster. |
| `type` | String | Yes | The type of predicted content to provide. Currently, the type is always "content". |
**Possible Content Types:**
1. **Text Content (String)** - Content for predicted output. This is usually the text of the file you are regenerating, with only small changes.
2. **Content Part Array (Array)** - An array of content parts with defined types. The supported options vary depending on the model used to generate the response. Can include text input.
**Content Part Array Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------- |
| `text` | String | Yes | Text content. |
| `type` | String | Yes | The type of content part. |
#### `audio` [#audio]
* Type: Object or null
* Required: No
Parameters for audio output. Required when requesting audio output with `modalities: ["audio"]`.
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `format` | String | Yes | Specifies the output audio format. Must be one of: wav, mp3, flac, opus, or pcm16. |
| `voice` | String | Yes | The voice used by the model for the response. Supported voices include: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, and shimmer. |
#### `temperature` [#temperature]
* Type: Number or null
* Required: No
* Default: 1
The sampling temperature to use, between 0 and 2. Higher values (e.g., 0.8) make the output more random, while lower values (e.g., 0.2) make it more concentrated and deterministic. We generally recommend changing this value or `top_p`, but not both.
#### `top_p` [#top_p]
* Type: Number or null
* Required: No
* Default: 1
An alternative to sampling temperature, called nucleus sampling, where the model considers the results of tokens with top\_p probability mass. Therefore, 0.1 means only considering tokens with the top 10% probability mass.
We generally recommend changing this value or `temperature`, but not both.
#### `n` [#n]
* Type: Integer or null
* Required: No
* Default: 1
How many chat completions to generate for each input message. Note that you will be charged for the total number of tokens generated across all choices. Keeping `n` to 1 can minimize costs.
#### `stop` [#stop]
* Type: String/Array/null
* Required: No
* Default: null
* Not supported by the latest inference models and .o3, o4-mini
API will stop generating more tokens for up to 4 sequences. The returned text will not include the stop sequence.
#### `max_tokens` [#max_tokens]
* Type: Integer or null
* Required: No
The maximum number of tokens that can be generated in a chat completion. This value can be used to control the text cost generated via API.
This value is now deprecated, replaced by `max_completion_tokens`, and is incompatible with .o1 series models.
#### `max_completion_tokens` [#max_completion_tokens]
* Type: Integer or null
* Required: No
The upper limit of tokens that can be generated in a completion, including visible output tokens and reasoning tokens.
#### `presence_penalty` [#presence_penalty]
* Type: Number or null
* Required: No
* Default: 0
A number between -2.0 and 2.0. Positive values penalize new tokens based on their occurrence so far in the text, thereby increasing the model's likelihood of discussing new topics.
#### `frequency_penalty` [#frequency_penalty]
* Type: Number or null
* Required: No
* Default: 0
A number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency so far in the text, thereby reducing the model's likelihood of repeating the same line word for word.
#### `logit_bias` [#logit_bias]
* Type: map
* Required: No
* Default: null
Modifies the likelihood of specified tokens appearing in the completion.
Accepts a JSON object that maps tokens (specified by token IDs in the tokenizer) to associated bias values from -100 to 100. Mathematically, bias is added to the logits of the model before sampling. The exact effect can vary by model, but values between -1 and 1 should reduce or increase the likelihood of selection; values like -100 or 100 should result in the relevant tokens being prohibited or exclusively selected.
#### `logprobs` [#logprobs]
* Type: Boolean or null
* Required: No
* Default: false
Whether to return log probabilities for output tokens. If true, returns log probabilities for each output token in `message.content`.
#### `user` [#user]
* Type: String
* Required: No
A unique identifier for the final user, which helps OpenAI monitor and detect abuse behavior. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids).
#### `service_tier` [#service_tier]
* Type: String or null
* Required: No
* Default: auto
Specifies the latency tier for processing the request. This parameter is relevant to customers subscribed to the scale tier service:
* If set to 'auto', and the project is enabled for Scale tier, the system will use scale tier credits until they are exhausted
* If set to 'auto', and the project is not enabled for Scale tier, the request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees
* If set to 'default', the request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees
* If set to 'flex', the request will be processed using the Flex Processing service tier. For details, please refer to the documentation.
* When not set, the default behavior is 'auto'
* When this parameter is set, the response body will include the used service\_tier
#### `stream_options` [#stream_options]
* Type: Object or null
* Required: No
* Default: null
Options for streaming responses. Only used when `stream: true`.
**Possible Properties:**
| Property | Type | Required | Description |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include_usage` | Boolean | No | If set, an additional block will be streamed before the data: \[DONE] message. The usage field on this block shows the token usage statistics for the entire request, and the choices field is always an empty array. All other blocks will also include a usage field, but its value will be null. Note: If the stream is interrupted, you may not receive a final usage block containing the total token usage of the request. |
#### `response_format` [#response_format]
* Type: Object
* Required: No
Specifies the format that the model must output.
* Set to `{ "type": "json_schema", "json_schema": {...} }` to enable structured output, ensuring the model matches your provided JSON schema.
* Set to `{ "type": "json_object" }` to enable JSON mode, ensuring the generated messages are valid JSON.
Important Note: When using JSON mode, you must also explicitly instruct the model to generate JSON via system or user messages. Otherwise, the model may generate endless blanks until it reaches token limits.
**Possible Types:**
| Type | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **text** | Default response format. Used to generate text responses. |
| **json\_schema** | JSON Schema response format. Used to generate structured JSON responses. Learn more about structured output. |
| **json\_object** | JSON object response format. An older method for generating JSON responses. For supported models, we recommend using json\_schema. |
**text Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | --------------------------------------------------------- |
| `type` | String | Yes | The type of response format being defined. Always "text". |
**json\_schema Properties:**
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `json_schema` | Object | Yes | Structured output configuration options, including JSON Schema. |
| `type` | String | Yes | The type of response format being defined. Always "json\_schema". |
**json\_schema.json\_schema Properties:**
| Property | Type | Required | Description |
| ------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | Yes | The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and hyphens, with a maximum length of 64. |
| `description` | String | No | A description of the purpose of the response format, used by the model to determine how to respond in that format. |
| `schema` | Object | No | The schema of the response format, described as a JSON Schema object. |
| `strict` | Boolean or null | No | Whether to enable strict schema adherence when generating output. If set to true, the model will always follow the exact schema defined in the schema field. strict is true, only a subset of JSON Schema is supported. |
**json\_object Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------------------------- |
| `type` | String | Yes | The type of response format being defined. Always "json\_object". |
#### `seed` [#seed]
* Type: Integer or null
* Required: No
Beta feature. If specified, our system will do its best to perform deterministic sampling, so repeated requests with the same seed and parameters should return the same results. No guarantee of determinism, you should refer to the system\_fingerprint of the response parameters to monitor backend changes.
#### `tools` [#tools]
* Type: Array
* Required: No
A list of tools that the model might call. Currently, only functions are supported as tools. Use this parameter to provide a list of functions that the model might generate JSON input for. Up to 128 functions are supported.
**Properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `function` | Object | Yes | Information about the function to be called |
| `type` | String | Yes | The type of tool. Currently, only function is supported. |
**function Properties:**
| Property | Type | Required | Description |
| ------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | Yes | The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and hyphens, with a maximum length of 64. |
| `description` | String | No | A description of the function's functionality, used by the model to determine when and how to call the function. |
| `parameters` | Object | No | The parameters accepted by the function, described as a JSON Schema object. Please refer to the guide for examples, and the JSON Schema reference for format documentation. Omitting the parameters definition results in an empty parameter list for the function. |
| `strict` | Boolean or null | No | Default: false. Whether to enable strict schema adherence when generating function calls. If set to true, the model will follow the exact schema defined in the parameters field. strict is true, only a subset of JSON Schema is supported. For details, please refer to the structured output section of the function calling guide. |
#### `functions` [#functions]
* Type: Array
* Required: No
* Note: Deprecated, recommended to use `tools`
A list of functions that the model might generate JSON input for.
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | String | Yes | The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and hyphens, with a maximum length of 64. |
| `description` | String | No | A description of the function's functionality, used by the model to determine when and how to call the function. |
| `parameters` | Object | No | The parameters accepted by the function, described as a JSON Schema object. Omitting the parameters definition results in an empty parameter list for the function. |
#### `tool_choice` [#tool_choice]
* Type: String or Object
* Required: No
Controls which tool (if any) the model should call:
* `none`: The model will not call any tools, but generate a message
* `auto`: The model can choose between generating a message or calling one or more tools
* `required`: The model must call one or more tools
* `{"type": "function", "function": {"name": "my_function"}}`: Forces the model to call a specific tool
Defaults to `none` when no tools are present, and to `auto` when tools are present.
**Possible Types:**
| Type | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **String** | none means the model will not call any tools, but generate a message. auto means the model can choose between generating a message or calling one or more tools. required means the model must call one or more tools. |
| **Object** | Specifies the tool that the model should use. Used to force the model to call a specific function. |
**Object Properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `function` | Object | Yes | Contains an object with function information |
| `type` | String | Yes | The type of tool. Currently, only function is supported. |
**function Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------- |
| `name` | String | Yes | The name of the function to be called. |
#### `function_call` [#function_call]
* Type: String or Object
* Required: No
* Default: `none` when no function, `auto` when function is present
* Note: Deprecated, recommended to use `tool_choice`
Controls which function (if any) the model should call:
* `none`: The model will not call any functions, but generate a message
* `auto`: The model can choose between generating a message or calling a function
* `{"name": "my_function"}`: Forces the model to call a specific function
**Object Type Properties:**
| Property | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------- |
| `name` | String | Yes | The name of the function to be called. |
#### `parallel_tool_calls` [#parallel_tool_calls]
* Type: Boolean
* Required: No
* Default: true
Whether to enable parallel function calls during tool usage.
#### `stream` [#stream]
* Type: Boolean or null
* Required: No
* Default: false
If set to true, model response data will be streamed to the client via server-sent events. Please refer to the streaming response section below for more information, and the streaming response guide for how to handle streaming events.
#### `top_logprobs` [#top_logprobs]
* Type: Integer or null
* Required: No
An integer between 0 and 20, specifying the number of most likely tokens at each token position, each with its associated log probability. If this parameter is used, `logprobs` must be true.
#### `web_search_options` [#web_search_options]
* Type: Object
* Required: No
This tool searches the web to obtain relevant results for the reply. Learn more about the web search tool.
**Possible Properties:**
| Property | Type | Required | Description |
| --------------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `search_context_size` | String | No | Advanced guidance for the context window size for search. Optional values are low, medium, or high. medium is the default. |
| `user_location` | Object or null | No | Approximate location parameters for the search. |
**user\_location Properties:**
| Property | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------- |
| `approximate` | Object | Yes | Approximate location parameters for the search. |
**approximate Properties:**
| Property | Type | Required | Description |
| ---------- | ------ | -------- | --------------------------------------------------------- |
| `city` | String | No | Free-text input for the user's city, e.g., San Francisco. |
| `country` | String | No | The user's two-letter ISO country code, e.g., US. |
| `region` | String | No | Free-text input for the user's region, e.g., California. |
| `timezone` | String | No | The user's IANA timezone, e.g., America/Los\_Angeles. |
| `type` | String | Yes | The type of location approximation. Always "approximate". |
## 📥 Response [#-response]
### Chat Completion Object [#chat-completion-object]
Returns a chat completion object, or a stream of chat completion chunk objects if the request was streamed.
#### `id` [#id]
* Type: String
* Description: The unique identifier of the response
#### `object` [#object]
* Type: String
* Description: The object type, value "chat.completion"
#### `created` [#created]
* Type: Integer
* Description: The timestamp of response creation
#### `model` [#model-1]
* Type: String
* Description: The name of the model used
#### `system_fingerprint` [#system_fingerprint]
* Type: String
* Description: The system fingerprint identifier, representing the backend configuration of the model run. Can be used together with the seed request parameter to understand when backend changes that might affect determinism have occurred.
#### `choices` [#choices]
* Type: Array
* Description: A list of generated response options. If n is greater than 1, multiple options can be present.
* Properties:
* `index`: The index of the option in the list of options.
* `message`: The chat completion message generated by the model.
* `role`: The role of the message author.
* `content`: The content of the message, which may be null.
* `refusal`: The rejection message generated by the model, which may be null.
* `annotations`: Annotations for the message, provided when applicable, e.g., when using the web search tool.
* `type`: The type of annotation. Always "url\_citation" when it's a URL reference.
* `url_citation`: The URL reference in the message.
* `start_index`: The index of the first character of the URL reference in the message.
* `end_index`: The index of the last character of the URL reference in the message.
* `url`: The URL of the network resource.
* `title`: The title of the network resource.
* `audio`: If audio output modality was requested, this object contains data from the model's audio response.
* `data`: The model's Base64 encoded audio bytes, in the format specified in the request.
* `id`: The unique identifier for this audio response.
* `transcript`: The transcription of the model's audio.
* `expires_at`: The Unix timestamp (seconds) at which this audio response is available for multi-turn conversations on the server.
* `function_call`: (Deprecated) The name and parameters of the function to be called, generated by the model. Replaced by `tool_calls`.
* `name`: The name of the function to be called.
* `arguments`: The parameters to be passed to the function, generated by the model in JSON format.
* `tool_calls`: Tool calls generated by the model, such as function calls.
* `id`: The ID of the tool call.
* `type`: The type of tool. Currently, only function is supported.
* `function`: The function called by the model.
* `name`: The name of the function to be called.
* `arguments`: The parameters to be passed to the function, generated by the model in JSON format. Note that the model does not always generate valid JSON, and may produce parameters not defined in your function schema. Before calling the function, please validate the parameters in your code.
* `logprobs`: Log probability information.
* `content`: A list of message content tokens with log probability information.
* `token`: The token.
* `logprob`: The log probability of this token, if it was among the top 20 most probable tokens. Otherwise, a value of -9999.0 is used to indicate this token is very unlikely.
* `bytes`: A list of integers representing the UTF-8 byte representation of the token. This is useful when a character is represented by multiple tokens and their byte representations must be combined to generate the correct text representation. If a token has no byte representation, it may be null.
* `top_logprobs`: A list of the most probable tokens at this token position and their log probabilities. In rare cases, the number of returned top\_logprobs may be less than the requested number.
* `refusal`: A list of message rejection tokens with log probability information.
* `finish_reason`: The reason the model stopped generating tokens. If the model reached a natural stopping point or provided a stop sequence, it is "stop"; if the maximum number of tokens specified in the request was reached, it is "length"; if content was omitted due to content filters, it is "content\_filter"; if the model called a tool, it is "tool\_calls"; if the model called a function, it is "function\_call" (deprecated).
#### `usage` [#usage]
* Type: Object
* Description: Usage statistics for the completion request.
* Properties:
* `prompt_tokens`: The number of tokens in the prompt.
* `completion_tokens`: The number of tokens in the generated completion.
* `total_tokens`: The total number of tokens used in the request (prompt + completion).
* `prompt_tokens_details`: A breakdown of the tokens used in the prompt.
* `cached_tokens`: The cached tokens in the prompt.
* `audio_tokens`: The audio input tokens in the prompt.
* `completion_tokens_details`: A breakdown of the tokens used in the completion.
* `reasoning_tokens`: The reasoning tokens generated by the model.
* `audio_tokens`: The audio tokens generated by the model.
* `accepted_prediction_tokens`: The number of tokens in the predicted output that appeared in the completion when using predicted output.
* `rejected_prediction_tokens`: The number of tokens in the predicted output that did not appear in the completion when using predicted output. However, like reasoning tokens, these tokens are still counted towards the total completion tokens for billing, output, and context window limits.
#### `service_tier` [#service_tier-1]
* Type: String or null
* Description: Specifies the latency tier for processing the request. This parameter is relevant to customers subscribed to the scale tier service:
* If set to 'auto', and the project is enabled for Scale tier, the system will use scale tier credits until they are exhausted
* If set to 'auto', and the project is not enabled for Scale tier, the request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees
* If set to 'default', the request will be processed using the default service tier, with lower normal operation time SLA and no latency guarantees
* If set to 'flex', the request will be processed using the Flex Processing service tier. For details, please refer to the documentation.
* When not set, the default behavior is 'auto'
* When this parameter is set, the response body will include the used service\_tier
#### Chat Completion Object Response Example [#chat-completion-object-response-example]
```json
{
"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
"object": "chat.completion",
"created": 1741570283,
"model": "gpt-4o-2024-08-06",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The image shows a wooden boardwalk path through dense green grass or meadow. The sky is bright blue with scattered clouds, creating a peaceful and serene atmosphere for the entire scene. Trees and shrubs can be seen in the background.",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1117,
"completion_tokens": 46,
"total_tokens": 1163,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default",
"system_fingerprint": "fp_fc9f1d7035"
}
```
### Chat Completion List Object [#chat-completion-list-object]
When multiple chat completions are returned, the API may return a chat completion list object.
#### `object` [#object-1]
* Type: String
* Description: The object type, always "list"
#### `data` [#data]
* Type: Array
* Description: An array of chat completion objects
#### `first_id` [#first_id]
* Type: String
* Description: The identifier of the first chat completion in the data array
#### `last_id` [#last_id]
* Type: String
* Description: The identifier of the last chat completion in the data array
#### `has_more` [#has_more]
* Type: Boolean
* Description: Indicates whether there are more chat completions available
#### Chat Completion List Response Example [#chat-completion-list-response-example]
```json
{
"object": "list",
"data": [
{
"object": "chat.completion",
"id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"model": "gpt-4o-2024-08-06",
"created": 1738960610,
"request_id": "req_ded8ab984ec4bf840f37566c1011c417",
"tool_choice": null,
"usage": {
"total_tokens": 31,
"completion_tokens": 18,
"prompt_tokens": 13
},
"seed": 4944116822809979520,
"top_p": 1.0,
"temperature": 1.0,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"system_fingerprint": "fp_50cad350e4",
"input_user": null,
"service_tier": "default",
"tools": null,
"metadata": {},
"choices": [
{
"index": 0,
"message": {
"content": "The circuit's heart hums low,\nLearning patterns in silence—\nFuture's quiet spark.",
"role": "assistant",
"tool_calls": null,
"function_call": null
},
"finish_reason": "stop",
"logprobs": null
}
],
"response_format": null
}
],
"first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"has_more": false
}
```
### Chat Completion Message List Object [#chat-completion-message-list-object]
The Chat Completion Message List object represents a list of chat messages.
#### `object` [#object-2]
* Type: String
* Description: The object type, always "list"
#### `data` [#data-1]
* Type: Array
* Description: An array of chat completion message objects, each object containing the following properties:
* `id`: The identifier of the chat message
* `role`: The role of the message author
* `content`: The content of the message, which may be null
* `name`: The name of the message sender, which may be null
* `refusal`: The rejection message generated by the model, which may be null
* `annotations`: Annotations for the message, provided when applicable, e.g., when using the web search tool
* `type`: The type of annotation. Always "url\_citation" when it's a URL reference.
* `url_citation`: The URL reference in the message.
* `start_index`: The index of the first character of the URL reference in the message.
* `end_index`: The index of the last character of the URL reference in the message.
* `url`: The URL of the network resource.
* `title`: The title of the network resource.
* `audio`: If audio output modality was requested, this object contains data from the model's audio response.
* `data`: The model's Base64 encoded audio bytes, in the format specified in the request.
* `id`: The unique identifier for this audio response.
* `transcript`: The transcription of the model's audio.
* `expires_at`: The Unix timestamp (seconds) at which this audio response is available for multi-turn conversations on the server.
* `function_call`: (Deprecated) The name and parameters of the function to be called, generated by the model. Replaced by `tool_calls`.
* `name`: The name of the function to be called.
* `arguments`: The parameters to be passed to the function, generated by the model in JSON format.
* `tool_calls`: Tool calls generated by the model, such as function calls
* `id`: The ID of the tool call.
* `type`: The type of tool. Currently, only function is supported.
* `function`: The function called by the model.
* `name`: The name of the function to be called.
* `arguments`: The parameters to be passed to the function, generated by the model in JSON format.
#### `first_id` [#first_id-1]
* Type: String
* Description: The identifier of the first chat message in the data array
#### `last_id` [#last_id-1]
* Type: String
* Description: The identifier of the last chat message in the data array
#### `has_more` [#has_more-1]
* Type: Boolean
* Description: Indicates whether there are more chat messages available
#### Chat Completion Message List Response Example [#chat-completion-message-list-response-example]
```json
{
"object": "list",
"data": [
{
"id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"role": "user",
"content": "Write a haiku about artificial intelligence",
"name": null,
"content_parts": null
}
],
"first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"has_more": false
}
```
# OpenAI Embeddings Format (/en/api/openai-embedding)
[OpenAI Embeddings](https://platform.openai.com/docs/api-reference/embeddings)
## 📝 Introduction [#-introduction]
Get vector representations of given input text that can be easily used by machine learning models and algorithms. For related guides, see [Embeddings Guide](https://platform.openai.com/docs/guides/embeddings).
Important notes:
* Some models may have limits on the total number of tokens in the input
* You can use [example Python code](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb) to calculate token counts
* For example: the text-embedding-ada-002 model outputs vectors with 1536 dimensions
## 💡 Request Examples [#-request-examples]
### Create Text Embeddings ✅ [#create-text-embeddings-]
```bash
curl https://api.zipflow.xyz/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"input": "The food was delicious and the waiter...",
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'
```
**Response Example:**
```json
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
-0.009327292,
// ... (1536 floating point numbers for ada-002)
-0.0028842222
],
"index": 0
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}
```
### Batch Create Embeddings ✅ [#batch-create-embeddings-]
```bash
curl https://api.zipflow.xyz/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"input": ["The food was delicious", "The waiter was friendly"],
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'
```
**Response Example:**
```json
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
// ... (1536 floating point numbers)
],
"index": 0
},
{
"object": "embedding",
"embedding": [
-0.008815289,
// ... (1536 floating point numbers)
],
"index": 1
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 12,
"total_tokens": 12
}
}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/embeddings
```
Create embedding vectors that represent the input text.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### `input` [#input]
* Type: String or array
* Required: Yes
The input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or an array of token arrays. Input must not exceed the model's maximum input token count (8192 tokens for text-embedding-ada-002), cannot be an empty string, and any array must have dimensions less than or equal to 2048.
#### `model` [#model]
* Type: String
* Required: Yes
The ID of the model to use. You can use the List models API to see all available models, or see the model overview for their descriptions.
#### `encoding_format` [#encoding_format]
* Type: String
* Required: No
* Default: float
The format to return the embeddings in. Can be float or base64.
#### `dimensions` [#dimensions]
* Type: Integer
* Required: No
The number of dimensions the generated output embeddings should have. Only supported in text-embedding-3 and newer models.
#### `user` [#user]
* Type: String
* Required: No
A unique identifier representing your end user, which can help OpenAI monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids).
## 📥 Response [#-response]
### Successful Response [#successful-response]
Returns a list of embedding objects.
#### `object` [#object]
* Type: String
* Description: Object type, value is "list"
#### `data` [#data]
* Type: Array
* Description: Array containing embedding objects
* Properties:
* `object`: Object type, value is "embedding"
* `embedding`: Embedding vector, list of floating point numbers. Vector length depends on the model
* `index`: Index of the embedding in the list
#### `model` [#model-1]
* Type: String
* Description: Name of the model used
#### `usage` [#usage]
* Type: Object
* Description: Token usage statistics
* Properties:
* `prompt_tokens`: Number of tokens used for prompt
* `total_tokens`: Total number of tokens
### Embedding Object [#embedding-object]
Represents an embedding vector returned by the embeddings endpoint.
```json
{
"object": "embedding",
"embedding": [
0.0023064255,
-0.009327292,
// ... (1536 floating point numbers total for ada-002)
-0.0028842222
],
"index": 0
}
```
#### `index` [#index]
* Type: Integer
* Description: Index of the embedding in the list
#### `embedding` [#embedding]
* Type: Array
* Description: Embedding vector, list of floating point numbers. Vector length depends on the model, see embeddings guide for details
#### `object` [#object-1]
* Type: String
* Description: Object type, always "embedding"
### Error Response [#error-response]
When there are issues with the request, the API will return an error response object with HTTP status codes in the 4XX-5XX range.
#### Common Error Status Codes [#common-error-status-codes]
* `401 Unauthorized`: Invalid or missing API key
* `400 Bad Request`: Invalid request parameters, such as empty input or exceeding token limits
* `429 Too Many Requests`: API call limit exceeded
* `500 Internal Server Error`: Internal server error
Error response example:
```json
{
"error": {
"message": "The input exceeds the maximum length. Please reduce the length of your input.",
"type": "invalid_request_error",
"param": "input",
"code": "context_length_exceeded"
}
}
```
# OpenAI Image Format (Image) (/en/api/openai-image)
[OpenAI Images](https://platform.openai.com/docs/api-reference/images)
## 📝 Introduction [#-introduction]
Given a text prompt and/or input image, the model will generate new images. OpenAI offers several powerful image generation models that can create, edit, and modify images based on natural language descriptions. Currently supported models include:
| Model | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **DALL·E Series** | Includes two versions, DALL·E 2 and DALL·E 3, which differ significantly in image quality, creative expression, and accuracy |
| **GPT-Image-1** | OpenAI's latest image model, supporting multi-image editing features, capable of creating new composite images based on multiple input images |
## 💡 Request Examples [#-request-examples]
### Create Image ✅ [#create-image-]
```bash
# 基础图片生成
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"n": 1,
"size": "1024x1024"
}'
# 高质量图片生成
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"quality": "hd",
"style": "vivid",
"size": "1024x1024"
}'
# 使用 base64 返回格式
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"response_format": "b64_json"
}'
```
**Response Example:**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://...",
"revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}
]
}
```
### Edit Image ✅ [#edit-image-]
```bash
# dall-e-2 图片编辑
curl https://api.zipflow.xyz/v1/images/edits \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F image="@otter.png" \
-F mask="@mask.png" \
-F prompt="一只戴着贝雷帽的可爱小海獭" \
-F n=2 \
-F size="1024x1024"
# gpt-image-1 多图片编辑示例
curl https://api.zipflow.xyz/v1/images/edits \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F "model=gpt-image-1" \
-F "image[]=@body-lotion.png" \
-F "image[]=@bath-bomb.png" \
-F "image[]=@incense-kit.png" \
-F "image[]=@soap.png" \
-F "prompt=创建一个包含这四个物品的精美礼品篮" \
-F "quality=high"
```
**Response Example (dall-e-2):**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}
```
**Response Example (gpt-image-1):**
```json
{
"created": 1713833628,
"data": [
{
"b64_json": "..."
}
],
"usage": {
"total_tokens": 100,
"input_tokens": 50,
"output_tokens": 50,
"input_tokens_details": {
"text_tokens": 10,
"image_tokens": 40
}
}
}
```
### Generate Image Variations ✅ [#generate-image-variations-]
```bash
curl https://api.zipflow.xyz/v1/images/variations \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F image="@otter.png" \
-F n=2 \
-F size="1024x1024"
```
**Response Example:**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}
```
## 📮 Request [#-request]
### Endpoints [#endpoints]
#### Create Image [#create-image]
```
POST /v1/images/generations
```
Creates an image given a text prompt.
#### Edit Image [#edit-image]
```
POST /v1/images/edits
```
Creates an edited or extended image based on one or more original images and a prompt. This endpoint supports the dall-e-2 and gpt-image-1 models.
#### Generate Variation [#generate-variation]
```
POST /v1/images/variations
```
Creates a variation of a given image.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$OPENAI_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### Create Image [#create-image-1]
##### `prompt` [#prompt]
* Type: string
* Required: Yes
* Description: A text description of the desired image(s).
* dall-e-2 maximum length is 1000 characters
* dall-e-3 maximum length is 4000 characters
* Tips:
* Use specific and detailed descriptions
* Include key visual elements
* Specify the desired artistic style
* Describe composition and perspective
##### `model` [#model]
* Type: string
* Required: No
* Default: dall-e-2
* Description: The model to use for image generation.
##### `n` [#n]
* Type: integer or null
* Required: No
* Default: 1
* Description: The number of images to generate. Must be between 1 and 10. dall-e-3 only supports n=1.
##### `quality` [#quality]
* Type: string
* Required: No
* Default: standard
* Description: The quality of the generated image. The hd option generates more detailed and consistent images. This parameter is only supported by dall-e-3.
##### `response_format` [#response_format]
* Type: string or null
* Required: No
* Default: url
* Description: The format in which the generated images are returned. Must be one of url or b64\_json. URLs are valid for 60 minutes after generation.
##### `size` [#size]
* Type: string or null
* Required: No
* Default: 1024x1024
* Description: The size of the generated images. dall-e-2 must be one of 256x256, 512x512, or 1024x1024. dall-e-3 must be one of 1024x1024, 1792x1024, or 1024x1792.
##### `style` [#style]
* Type: string or null
* Required: No
* Default: vivid
* Description: The style of the generated images. Must be one of vivid or natural. vivid tends to generate hyper-real and dramatic images, while natural tends to generate more natural, less hyper-real images. This parameter is only supported by dall-e-3.
##### `user` [#user]
* Type: string
* Required: No
* Description: A unique identifier representing your end-user, which can help OpenAI monitor and detect abuse.
#### `moderation` [#moderation]
* Type: string
* Required: No
* Default: auto
* Description: auto: Standard moderation, designed to limit the generation of certain content categories that may not be age-appropriate. low: Less restrictive moderation.
#### Edit Image [#edit-image-1]
##### `image` [#image]
* Type: file or file array
* Required: Yes
* Description: The image to be edited.
* For dall-e-2: Must be a valid PNG file, less than 4MB, and square. If no mask is provided, the image must have transparency, which will be used as the mask.
* For gpt-image-1: Multiple images can be provided as an array. Each image should be a PNG, WEBP, or JPG file, less than 25MB.
##### `prompt` [#prompt-1]
* Type: string
* Required: Yes
* Description: A text description of the desired image(s).
* dall-e-2 maximum length is 1000 characters
* gpt-image-1 maximum length is 32000 characters
##### `mask` [#mask]
* Type: file
* Required: No
* Description: An additional image whose fully transparent areas (e.g., alpha zero areas) indicate where the image should be edited. If multiple images are provided, the mask will be applied to the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as the image.
##### `model` [#model-1]
* Type: string
* Required: No
* Default: dall-e-2
* Description: The model to use for image generation. Supports dall-e-2 and gpt-image-1. Defaults to dall-e-2 unless gpt-image-1 specific parameters are used.
##### `quality` [#quality-1]
* Type: string or null
* Required: No
* Default: auto
* Description: The quality of the generated image.
* gpt-image-1 supports high, medium, and low
* dall-e-2 only supports standard
* Defaults to auto
##### `size` [#size-1]
* Type: string or null
* Required: No
* Default: 1024x1024
* Description: The size of the generated images.
* gpt-image-1 must be one of 1024x1024, 1536x1024 (landscape), 1024x1536 (portrait), or auto (default)
* dall-e-2 must be one of 256x256, 512x512, or 1024x1024
Other parameters are the same as the Create Image interface.
#### Generate Variations [#generate-variations]
##### `image` [#image-1]
* Type: file
* Required: Yes
* Description: The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
Other parameters are the same as the Create Image interface.
## 📥 Response [#-response]
### Successful Response [#successful-response]
All three endpoints return a response containing a list of image objects.
#### `created` [#created]
* Type: integer
* Description: The timestamp when the response was created
#### `data` [#data]
* Type: array
* Description: A list of generated image objects
#### `usage` (Only applicable to gpt-image-1) [#usage-only-applicable-to-gpt-image-1]
* Type: object
* Description: Token usage for the API call
* `total_tokens`: Total tokens used
* `input_tokens`: Tokens used for input
* `output_tokens`: Tokens used for output
* `input_tokens_details`: Detailed information on input tokens (text tokens and image tokens)
### Image Object [#image-object]
#### `b64_json` [#b64_json]
* Type: string
* Description: If `response_format` is `b64_json`, this contains the base64 encoded JSON of the generated image
#### `url` [#url]
* Type: string
* Description: If `response_format` is `url` (default), this contains the URL of the generated image
#### `revised_prompt` [#revised_prompt]
* Type: string
* Description: If the prompt was modified, this contains the revised prompt used to generate the image
Example Image Object:
```json
{
"url": "https://...",
"revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}
```
## 🌟 Best Practices [#-best-practices]
### Prompt Writing Suggestions [#prompt-writing-suggestions]
1. Use clear and specific descriptions
2. Specify important visual details
3. Describe the desired artistic style and atmosphere
4. Include instructions for composition and perspective
### Parameter Selection Suggestions [#parameter-selection-suggestions]
1. Model Selection
* dall-e-3: Suitable for scenarios requiring high quality and precise details
* dall-e-2: Suitable for rapid prototyping or simple image generation
2. Size Selection
* 1024x1024: Best choice for general scenarios
* 1792x1024/1024x1792: Suitable for landscape/portrait scenarios
* Smaller sizes: Suitable for thumbnails or quick previews
3. Quality and Style
* quality=hd: Used for images requiring fine detail
* style=vivid: Suitable for creative and artistic effects
* style=natural: Suitable for realistic scene reproduction
### Common Issues [#common-issues]
1. Image generation failure
* Check if the prompt complies with content policies
* Confirm file format and size limits
* Verify API key permissions
2. Results do not match expectations
* Optimize the prompt description
* Adjust quality and style parameters
* Consider using image editing or variation features
# OpenAI Realtime API (/en/api/openai-realtime)
* [OpenAI Realtime WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc)
* [OpenAI Realtime WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
## 📝 Overview [#-overview]
### Introduction [#introduction]
OpenAI Realtime API provides two connection methods:
1. WebRTC - For real-time audio/video interaction in browsers and mobile clients
2. WebSocket - For server-to-server application integration
### Use Cases [#use-cases]
* Real-time voice conversations
* Audio/video conferencing
* Real-time translation
* Speech transcription
* Real-time code generation
* Server-side real-time integration
### Key Features [#key-features]
* Bidirectional audio streaming
* Mixed text and audio conversations
* Function calling support
* Automatic Voice Activity Detection (VAD)
* Audio transcription capabilities
* WebSocket server-side integration
## 🔐 Authentication & Security [#-authentication--security]
### Authentication Methods [#authentication-methods]
1. Standard API Key (server-side only)
2. Ephemeral Token (client-side use)
### Ephemeral Token [#ephemeral-token]
* Validity: 1 minute
* Usage limit: Single connection
* Generation: Created via server-side API
```http
POST https://api.zipflow.xyz/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer $API_KEY
{
"model": "gpt-4o-realtime-preview-2024-12-17",
"voice": "verse"
}
```
### Security Recommendations [#security-recommendations]
* Never expose standard API keys on the client side
* Use HTTPS/WSS for communication
* Implement appropriate access controls
* Monitor for unusual activity
## 🔌 Connection Establishment [#-connection-establishment]
### WebRTC Connection [#webrtc-connection]
* URL: `https://api.zipflow.xyz/v1/realtime`
* Query parameters: `model`
* Headers:
* `Authorization: Bearer EPHEMERAL_KEY`
* `Content-Type: application/sdp`
### WebSocket Connection [#websocket-connection]
* URL: `wss://api.zipflow.xyz/v1/realtime`
* Query parameters: `model`
* Headers:
* `Authorization: Bearer YOUR_API_KEY`
* `OpenAI-Beta: realtime=v1`
### Connection Flow [#connection-flow]
```mermaid
sequenceDiagram
participant Client
participant Server
participant OpenAI
alt WebRTC Connection
Client->>Server: Request ephemeral token
Server->>OpenAI: Create session
OpenAI-->>Server: Return ephemeral token
Server-->>Client: Return ephemeral token
Client->>OpenAI: Create WebRTC offer
OpenAI-->>Client: Return answer
Note over Client,OpenAI: Establish WebRTC connection
Client->>OpenAI: Create data channel
OpenAI-->>Client: Confirm data channel
else WebSocket Connection
Server->>OpenAI: Establish WebSocket connection
OpenAI-->>Server: Confirm connection
Note over Server,OpenAI: Begin real-time conversation
end
```
### Data Channel [#data-channel]
* Name: `oai-events`
* Purpose: Event transmission
* Format: JSON
### Audio Stream [#audio-stream]
* Input: `addTrack()`
* Output: `ontrack` event
## 💬 Conversation Interaction [#-conversation-interaction]
### Conversation Modes [#conversation-modes]
1. Text-only conversations
2. Voice conversations
3. Mixed conversations
### Session Management [#session-management]
* Create session
* Update session
* End session
* Session configuration
### Event Types [#event-types]
* Text events
* Audio events
* Function calls
* Status updates
* Error events
## ⚙️ Configuration Options [#️-configuration-options]
### Audio Configuration [#audio-configuration]
* Input formats
* `pcm16`
* `g711_ulaw`
* `g711_alaw`
* Output formats
* `pcm16`
* `g711_ulaw`
* `g711_alaw`
* Voice types
* `alloy`
* `echo`
* `shimmer`
### Model Configuration [#model-configuration]
* Temperature
* Maximum output length
* System prompt
* Tool configuration
### VAD Configuration [#vad-configuration]
* Threshold
* Silence duration
* Prefix padding
## 💡 Request Examples [#-request-examples]
### WebRTC Connection ❌ [#webrtc-connection-]
#### Client Implementation (Browser) [#client-implementation-browser]
```javascript
async function init() {
// Get ephemeral key from server - see server code below
const tokenResponse = await fetch("/session");
const data = await tokenResponse.json();
const EPHEMERAL_KEY = data.client_secret.value;
// Create peer connection
const pc = new RTCPeerConnection();
// Set up remote audio from model playback
const audioEl = document.createElement("audio");
audioEl.autoplay = true;
pc.ontrack = e => audioEl.srcObject = e.streams[0];
// Add local audio track from browser microphone input
const ms = await navigator.mediaDevices.getUserMedia({
audio: true
});
pc.addTrack(ms.getTracks()[0]);
// Set up data channel for sending and receiving events
const dc = pc.createDataChannel("oai-events");
dc.addEventListener("message", (e) => {
// Receive real-time server events here!
console.log(e);
});
// Start session using Session Description Protocol (SDP)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const baseUrl = "https://api.zipflow.xyz/v1/realtime";
const model = "gpt-4o-realtime-preview-2024-12-17";
const sdpResponse = await fetch(`${baseUrl}?model=${model}`, {
method: "POST",
body: offer.sdp,
headers: {
Authorization: `Bearer ${EPHEMERAL_KEY}`,
"Content-Type": "application/sdp"
},
});
const answer = {
type: "answer",
sdp: await sdpResponse.text(),
};
await pc.setRemoteDescription(answer);
}
init();
```
#### Server Implementation (Node.js) [#server-implementation-nodejs]
```javascript
import express from "express";
const app = express();
// Create an endpoint for generating ephemeral tokens
// This endpoint works with the client code above
app.get("/session", async (req, res) => {
const r = await fetch("https://api.zipflow.xyz/v1/realtime/sessions", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-4o-realtime-preview-2024-12-17",
voice: "verse",
}),
});
const data = await r.json();
// Send the JSON received from OpenAI REST API back to client
res.send(data);
});
app.listen(3000);
```
#### WebRTC Event Send/Receive Example [#webrtc-event-sendreceive-example]
```javascript
// Create data channel from peer connection
const dc = pc.createDataChannel("oai-events");
// Listen for server events on data channel
// Event data needs to be parsed from JSON string
dc.addEventListener("message", (e) => {
const realtimeEvent = JSON.parse(e.data);
console.log(realtimeEvent);
});
// Send client event: serialize valid client events to
// JSON and send via data channel
const responseCreate = {
type: "response.create",
response: {
modalities: ["text"],
instructions: "Write a haiku about code",
},
};
dc.send(JSON.stringify(responseCreate));
```
### WebSocket Connection ✅ [#websocket-connection-]
#### Node.js (ws module) [#nodejs-ws-module]
```javascript
import WebSocket from "ws";
const url = "wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17";
const ws = new WebSocket(url, {
headers: {
"Authorization": "Bearer " + process.env.API_KEY,
"OpenAI-Beta": "realtime=v1",
},
});
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});
```
#### Python (websocket-client) [#python-websocket-client]
```python
# Requires websocket-client library:
# pip install websocket-client
import os
import json
import websocket
API_KEY = os.environ.get("API_KEY")
url = "wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17"
headers = [
"Authorization: Bearer " + API_KEY,
"OpenAI-Beta: realtime=v1"
]
def on_open(ws):
print("Connected to server.");
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
ws = websocket.WebSocketApp(
url,
header=headers,
on_open=on_open,
on_message=on_message,
)
ws.run_forever()
```
#### Browser (Standard WebSocket) [#browser-standard-websocket]
```javascript
/*
Note: In browser and other client environments, we recommend using WebRTC.
But in Deno and Cloudflare Workers and other browser-like environments,
you can also use the standard WebSocket interface.
*/
const ws = new WebSocket(
"wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17",
[
"realtime",
// Authentication
"openai-insecure-api-key." + API_KEY,
// Optional
"openai-organization." + OPENAI_ORG_ID,
"openai-project." + OPENAI_PROJECT_ID,
// Beta protocol, required
"openai-beta.realtime-v1"
]
);
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(message.data);
});
```
#### Message Send/Receive Example [#message-sendreceive-example]
##### Node.js/Browser [#nodejsbrowser]
```javascript
// Receive server events
ws.on("message", function incoming(message) {
// Need to parse message data from JSON
const serverEvent = JSON.parse(message.data)
console.log(serverEvent);
});
// Send events, create JSON data structure conforming to client event format
const event = {
type: "response.create",
response: {
modalities: ["audio", "text"],
instructions: "Give me a haiku about code.",
}
};
ws.send(JSON.stringify(event));
```
##### Python [#python]
```python
# Send client events, serialize dictionary to JSON
def on_open(ws):
print("Connected to server.");
event = {
"type": "response.create",
"response": {
"modalities": ["text"],
"instructions": "Please assist the user."
}
}
ws.send(json.dumps(event))
# Receive messages need to parse message payload from JSON
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
```
## ⚠️ Error Handling [#️-error-handling]
### Common Errors [#common-errors]
1. Connection errors
* Network issues
* Authentication failures
* Configuration errors
2. Audio errors
* Device permissions
* Unsupported formats
* Codec issues
3. Session errors
* Token expiration
* Session timeout
* Concurrency limits
### Error Recovery [#error-recovery]
1. Automatic reconnection
2. Session recovery
3. Error retry
4. Graceful degradation
## 📝 Event Reference [#-event-reference]
### Common Request Headers [#common-request-headers]
All events need to include the following request headers:
| Header | Type | Description | Example Value |
| ------------- | ------ | -------------------- | ---------------- |
| Authorization | String | Authentication token | Bearer $API\_KEY |
| OpenAI-Beta | String | API version | realtime=v1 |
### Client Events [#client-events]
#### session.update [#sessionupdate]
Update the default configuration for the session.
| Parameter | Type | Required | Description | Example Value/Optional Values |
| ------------------------------------- | -------------- | -------- | -------------------------------------------- | ------------------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_123 |
| type | String | No | Event type | session.update |
| modalities | String array | No | Modality types the model can respond with | \["text", "audio"] |
| instructions | String | No | System instructions prepended to model calls | "Your knowledge cutoff is 2023-10..." |
| voice | String | No | Voice type used by the model | alloy, echo, shimmer |
| input\_audio\_format | String | No | Input audio format | pcm16, g711\_ulaw, g711\_alaw |
| output\_audio\_format | String | No | Output audio format | pcm16, g711\_ulaw, g711\_alaw |
| input\_audio\_transcription.model | String | No | Model used for transcription | whisper-1 |
| turn\_detection.type | String | No | Voice detection type | server\_vad |
| turn\_detection.threshold | Number | No | VAD activation threshold (0.0-1.0) | 0.8 |
| turn\_detection.prefix\_padding\_ms | Integer | No | Audio duration included before speech starts | 500 |
| turn\_detection.silence\_duration\_ms | Integer | No | Silence duration to detect speech stop | 1000 |
| tools | Array | No | List of tools available to the model | \[] |
| tool\_choice | String | No | How the model chooses tools | auto/none/required |
| temperature | Number | No | Model sampling temperature | 0.8 |
| max\_output\_tokens | String/Integer | No | Maximum tokens per response | "inf"/4096 |
#### input\_audio\_buffer.append [#input_audio_bufferappend]
Append audio data to the input audio buffer.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | --------------------------------- | --------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_456 |
| type | String | No | Event type | input\_audio\_buffer.append |
| audio | String | No | Base64-encoded audio data | Base64EncodedAudioData |
#### input\_audio\_buffer.commit [#input_audio_buffercommit]
Commit the audio data in the buffer as a user message.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | --------------------------------- | --------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_789 |
| type | String | No | Event type | input\_audio\_buffer.commit |
#### input\_audio\_buffer.clear [#input_audio_bufferclear]
Clear all audio data from the input audio buffer.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | --------------------------------- | -------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_012 |
| type | String | No | Event type | input\_audio\_buffer.clear |
#### conversation.item.create [#conversationitemcreate]
Add a new conversation item to the conversation.
| Parameter | Type | Required | Description | Example Value |
| ------------------ | ------ | -------- | ------------------------------------------- | --------------------------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_345 |
| type | String | No | Event type | conversation.item.create |
| previous\_item\_id | String | No | New item will be inserted after this ID | null |
| item.id | String | No | Unique identifier for the conversation item | msg\_001 |
| item.type | String | No | Type of conversation item | message/function\_call/function\_call\_output |
| item.status | String | No | Status of conversation item | completed/in\_progress/incomplete |
| item.role | String | No | Role of message sender | user/assistant/system |
| item.content | Array | No | Message content | \[text/audio/transcript] |
| item.call\_id | String | No | ID of function call | call\_001 |
| item.name | String | No | Name of called function | function\_name |
| item.arguments | String | No | Arguments for function call | \{"param": "value"} |
| item.output | String | No | Output result of function call | \{"result": "value"} |
#### conversation.item.truncate [#conversationitemtruncate]
Truncate audio content in assistant messages.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | ---------------------------------------- | -------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_678 |
| type | String | No | Event type | conversation.item.truncate |
| item\_id | String | No | ID of assistant message item to truncate | msg\_002 |
| content\_index | Integer | No | Index of content part to truncate | 0 |
| audio\_end\_ms | Integer | No | End time point for audio truncation | 1500 |
#### conversation.item.delete [#conversationitemdelete]
Delete the specified conversation item from conversation history.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | --------------------------------- | ------------------------ |
| event\_id | String | No | Client-generated event identifier | event\_901 |
| type | String | No | Event type | conversation.item.delete |
| item\_id | String | No | ID of conversation item to delete | msg\_003 |
#### response.create [#responsecreate]
Trigger response generation.
| Parameter | Type | Required | Description | Example Value |
| ------------------------------ | -------------- | -------- | ------------------------------------ | -------------------------------- |
| event\_id | String | No | Client-generated event identifier | event\_234 |
| type | String | No | Event type | response.create |
| response.modalities | String array | No | Modality types for response | \["text", "audio"] |
| response.instructions | String | No | Instructions for the model | "Please assist the user." |
| response.voice | String | No | Voice type used by the model | alloy/echo/shimmer |
| response.output\_audio\_format | String | No | Output audio format | pcm16 |
| response.tools | Array | No | List of tools available to the model | \["type", "name", "description"] |
| response.tool\_choice | String | No | How the model chooses tools | auto |
| response.temperature | Number | No | Sampling temperature | 0.7 |
| response.max\_output\_tokens | Integer/String | No | Maximum output tokens | 150/"inf" |
#### response.cancel [#responsecancel]
Cancel ongoing response generation.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | --------------------------------- | --------------- |
| event\_id | String | No | Client-generated event identifier | event\_567 |
| type | String | No | Event type | response.cancel |
### Server Events [#server-events]
#### error [#error]
Event returned when an error occurs.
| Parameter | Type | Required | Description | Example Value |
| --------------- | ------------ | -------- | ---------------------------------- | ------------------------------------- |
| event\_id | String array | No | Unique identifier for server event | \["event\_890"] |
| type | String | No | Event type | error |
| error.type | String | No | Error type | invalid\_request\_error/server\_error |
| error.code | String | No | Error code | invalid\_event |
| error.message | String | No | Human-readable error message | "The 'type' field is missing." |
| error.param | String | No | Parameter related to error | null |
| error.event\_id | String | No | ID of related event | event\_567 |
#### conversation.item.input\_audio\_transcription.completed [#conversationiteminput_audio_transcriptioncompleted]
Returned when input audio transcription is enabled and transcription succeeds.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | -------------------------------------- | ------------------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_2122 |
| type | String | No | Event type | conversation.item.input\_audio\_transcription.completed |
| item\_id | String | No | ID of user message item | msg\_003 |
| content\_index | Integer | No | Index of content part containing audio | 0 |
| transcript | String | No | Transcribed text content | "Hello, how are you?" |
#### conversation.item.input\_audio\_transcription.failed [#conversationiteminput_audio_transcriptionfailed]
Returned when input audio transcription is configured but transcription request for user message fails.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------------ | -------- | -------------------------------------- | --------------------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_2324 |
| type | String array | No | Event type | \["conversation.item.input\_audio\_transcription.failed"] |
| item\_id | String | No | ID of user message item | msg\_003 |
| content\_index | Integer | No | Index of content part containing audio | 0 |
| error.type | String | No | Error type | transcription\_error |
| error.code | String | No | Error code | audio\_unintelligible |
| error.message | String | No | Human-readable error message | "The audio could not be transcribed." |
| error.param | String | No | Parameter related to error | null |
#### conversation.item.truncated [#conversationitemtruncated]
Returned when client truncates previous assistant audio message item.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | -------------------------------------------------- | --------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_2526 |
| type | String | No | Event type | conversation.item.truncated |
| item\_id | String | No | ID of truncated assistant message item | msg\_004 |
| content\_index | Integer | No | Index of truncated content part | 0 |
| audio\_end\_ms | Integer | No | Time point when audio was truncated (milliseconds) | 1500 |
#### conversation.item.deleted [#conversationitemdeleted]
Returned when an item in the conversation is deleted.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | ---------------------------------- | ------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_2728 |
| type | String | No | Event type | conversation.item.deleted |
| item\_id | String | No | ID of deleted conversation item | msg\_005 |
#### input\_audio\_buffer.committed [#input_audio_buffercommitted]
Returned when audio buffer data is committed.
| Parameter | Type | Required | Description | Example Value |
| ------------------ | ------ | -------- | ---------------------------------------------------- | ------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_1121 |
| type | String | No | Event type | input\_audio\_buffer.committed |
| previous\_item\_id | String | No | New conversation item will be inserted after this ID | msg\_001 |
| item\_id | String | No | ID of user message item to be created | msg\_002 |
#### input\_audio\_buffer.cleared [#input_audio_buffercleared]
Returned when client clears input audio buffer.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | ---------------------------------- | ---------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_1314 |
| type | String | No | Event type | input\_audio\_buffer.cleared |
#### input\_audio\_buffer.speech\_started [#input_audio_bufferspeech_started]
In server voice detection mode, returned when voice input is detected.
| Parameter | Type | Required | Description | Example Value |
| ---------------- | ------- | -------- | ------------------------------------------------------ | ------------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_1516 |
| type | String | No | Event type | input\_audio\_buffer.speech\_started |
| audio\_start\_ms | Integer | No | Milliseconds from session start to voice detection | 1000 |
| item\_id | String | No | ID of user message item to be created when voice stops | msg\_003 |
#### input\_audio\_buffer.speech\_stopped [#input_audio_bufferspeech_stopped]
In server voice detection mode, returned when voice input stops.
| Parameter | Type | Required | Description | Example Value |
| ---------------- | ------- | -------- | ------------------------------------------------------- | ------------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_1718 |
| type | String | No | Event type | input\_audio\_buffer.speech\_stopped |
| audio\_start\_ms | Integer | No | Milliseconds from session start to voice stop detection | 2000 |
| item\_id | String | No | ID of user message item to be created | msg\_003 |
#### response.created [#responsecreated]
Returned when a new response is created.
| Parameter | Type | Required | Description | Example Value |
| ------------------------ | ------------ | -------- | ------------------------------------------ | ----------------- |
| event\_id | String | No | Unique identifier for server event | event\_2930 |
| type | String | No | Event type | response.created |
| response.id | String | No | Unique identifier for response | resp\_001 |
| response.object | String | No | Object type | realtime.response |
| response.status | String | No | Status of response | in\_progress |
| response.status\_details | Object | No | Additional details about status | null |
| response.output | String array | No | List of output items generated by response | \["\[]"] |
| response.usage | Object | No | Usage statistics for response | null |
#### response.done [#responsedone]
Returned when response streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| ----------------------------- | ------------ | -------- | ------------------------------------------ | ------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_3132 |
| type | String | No | Event type | response.done |
| response.id | String | No | Unique identifier for response | resp\_001 |
| response.object | String | No | Object type | realtime.response |
| response.status | String | No | Final status of response | completed/cancelled/failed/incomplete |
| response.status\_details | Object | No | Additional details about status | null |
| response.output | String array | No | List of output items generated by response | \["\[...]"] |
| response.usage.total\_tokens | Integer | No | Total tokens | 50 |
| response.usage.input\_tokens | Integer | No | Input tokens | 20 |
| response.usage.output\_tokens | Integer | No | Output tokens | 30 |
#### response.output\_item.added [#responseoutput_itemadded]
Returned when a new output item is created during response generation.
| Parameter | Type | Required | Description | Example Value |
| ------------- | ------ | -------- | ----------------------------------------- | --------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_3334 |
| type | String | No | Event type | response.output\_item.added |
| response\_id | String | No | ID of response the output item belongs to | resp\_001 |
| output\_index | String | No | Index of output item in response | 0 |
| item.id | String | No | Unique identifier for output item | msg\_007 |
| item.object | String | No | Object type | realtime.item |
| item.type | String | No | Type of output item | message/function\_call/function\_call\_output |
| item.status | String | No | Status of output item | in\_progress/completed |
| item.role | String | No | Role associated with output item | assistant |
| item.content | Array | No | Content of output item | \["type", "text", "audio", "transcript"] |
#### response.output\_item.done [#responseoutput_itemdone]
Returned when output item streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| ------------- | ------ | -------- | ----------------------------------------- | --------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_3536 |
| type | String | No | Event type | response.output\_item.done |
| response\_id | String | No | ID of response the output item belongs to | resp\_001 |
| output\_index | String | No | Index of output item in response | 0 |
| item.id | String | No | Unique identifier for output item | msg\_007 |
| item.object | String | No | Object type | realtime.item |
| item.type | String | No | Type of output item | message/function\_call/function\_call\_output |
| item.status | String | No | Final status of output item | completed/incomplete |
| item.role | String | No | Role associated with output item | assistant |
| item.content | Array | No | Content of output item | \["type", "text", "audio", "transcript"] |
#### response.content\_part.added [#responsecontent_partadded]
Returned when a new content part is added to assistant message item during response generation.
| Parameter | Type | Required | Description | Example Value |
| --------------- | ------- | -------- | --------------------------------------------------- | ------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_3738 |
| type | String | No | Event type | response.content\_part.added |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item to add content part to | msg\_007 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| part.type | String | No | Content type | text/audio |
| part.text | String | No | Text content | "Hello" |
| part.audio | String | No | Base64-encoded audio data | "base64\_encoded\_audio\_data" |
| part.transcript | String | No | Transcribed text of audio | "Hello" |
#### response.content\_part.done [#responsecontent_partdone]
Returned when content part in assistant message item streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| --------------- | ------- | -------- | --------------------------------------------------- | ------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_3940 |
| type | String | No | Event type | response.content\_part.done |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item to add content part to | msg\_007 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| part.type | String | No | Content type | text/audio |
| part.text | String | No | Text content | "Hello" |
| part.audio | String | No | Base64-encoded audio data | "base64\_encoded\_audio\_data" |
| part.transcript | String | No | Transcribed text of audio | "Hello" |
#### response.text.delta [#responsetextdelta]
Returned when text value of "text" type content part is updated.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | ------------------- |
| event\_id | String | No | Unique identifier for server event | event\_4142 |
| type | String | No | Event type | response.text.delta |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_007 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| delta | String | No | Text delta update content | "Sure, I can h" |
#### response.text.done [#responsetextdone]
Returned when "text" type content part text streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | ----------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_4344 |
| type | String | No | Event type | response.text.done |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_007 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| delta | String | No | Final complete text content | "Sure, I can help with that." |
#### response.audio\_transcript.delta [#responseaudio_transcriptdelta]
Returned when transcription content of model-generated audio output is updated.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | -------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_4546 |
| type | String | No | Event type | response.audio\_transcript.delta |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_008 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| delta | String | No | Transcription text delta update content | "Hello, how can I a" |
#### response.audio\_transcript.done [#responseaudio_transcriptdone]
Returned when transcription of model-generated audio output streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | ------------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_4748 |
| type | String | No | Event type | response.audio\_transcript.done |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_008 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| transcript | String | No | Final complete transcribed text of audio | "Hello, how can I assist you today?" |
#### response.audio.delta [#responseaudiodelta]
Returned when model-generated audio content is updated.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | ------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_4950 |
| type | String | No | Event type | response.audio.delta |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_008 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
| delta | String | No | Base64-encoded audio data delta | "Base64EncodedAudioDelta" |
#### response.audio.done [#responseaudiodone]
Returned when model-generated audio is complete.
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | --------------------------------------------------- | ------------------- |
| event\_id | String | No | Unique identifier for server event | event\_5152 |
| type | String | No | Event type | response.audio.done |
| response\_id | String | No | ID of response | resp\_001 |
| item\_id | String | No | ID of message item | msg\_008 |
| output\_index | Integer | No | Index of output item in response | 0 |
| content\_index | Integer | No | Index of content part in message item content array | 0 |
### Function Calling [#function-calling]
#### response.function\_call\_arguments.delta [#responsefunction_call_argumentsdelta]
Returned when model-generated function call arguments are updated.
| Parameter | Type | Required | Description | Example Value |
| ------------- | ------- | -------- | ----------------------------------------- | ---------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_5354 |
| type | String | No | Event type | response.function\_call\_arguments.delta |
| response\_id | String | No | ID of response | resp\_002 |
| item\_id | String | No | ID of message item | fc\_001 |
| output\_index | Integer | No | Index of output item in response | 0 |
| call\_id | String | No | ID of function call | call\_001 |
| delta | String | No | JSON format function call arguments delta | "\{"location": "San"" |
#### response.function\_call\_arguments.done [#responsefunction_call_argumentsdone]
Returned when model-generated function call arguments streaming is complete.
| Parameter | Type | Required | Description | Example Value |
| ------------- | ------- | -------- | ---------------------------------------------------- | --------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_5556 |
| type | String | No | Event type | response.function\_call\_arguments.done |
| response\_id | String | No | ID of response | resp\_002 |
| item\_id | String | No | ID of message item | fc\_001 |
| output\_index | Integer | No | Index of output item in response | 0 |
| call\_id | String | No | ID of function call | call\_001 |
| arguments | String | No | Final complete function call arguments (JSON format) | "\{"location": "San Francisco"}" |
### Other Status Updates [#other-status-updates]
#### rate\_limits.updated [#rate_limitsupdated]
Triggered after each "response.done" event to indicate updated rate limits.
| Parameter | Type | Required | Description | Example Value |
| ------------ | ------------ | -------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_5758 |
| type | String | No | Event type | rate\_limits.updated |
| rate\_limits | Object array | No | List of rate limit information | \[\{"name": "requests\_per\_min", "limit": 60, "remaining": 45, "reset\_seconds": 35}] |
#### conversation.created [#conversationcreated]
Returned when conversation is created.
| Parameter | Type | Required | Description | Example Value |
| ------------ | ------ | -------- | ---------------------------------- | ------------------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_9101 |
| type | String | No | Event type | conversation.created |
| conversation | Object | No | Conversation resource object | \{"id": "conv\_001", "object": "realtime.conversation"} |
#### conversation.item.created [#conversationitemcreated]
Returned when conversation item is created.
| Parameter | Type | Required | Description | Example Value |
| ------------------ | ------ | -------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| event\_id | String | No | Unique identifier for server event | event\_1920 |
| type | String | No | Event type | conversation.item.created |
| previous\_item\_id | String | No | ID of previous conversation item | msg\_002 |
| item | Object | No | Conversation item object | \{"id": "msg\_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": \[\{"type": "text", "text": "Hello"}]} |
#### session.created [#sessioncreated]
Returned when session is created.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_1234 |
| type | String | No | Event type | session.created |
| session | Object | No | Session object | \{"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": \["text", "audio"]} |
#### session.updated [#sessionupdated]
Returned when session is updated.
| Parameter | Type | Required | Description | Example Value |
| --------- | ------ | -------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| event\_id | String | No | Unique identifier for server event | event\_5678 |
| type | String | No | Event type | session.updated |
| session | Object | No | Updated session object | \{"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": \["text", "audio"]} |
### Rate Limit Event Parameter Table [#rate-limit-event-parameter-table]
| Parameter | Type | Required | Description | Example Value |
| -------------- | ------- | -------- | -------------------------- | ------------------ |
| name | String | Yes | Limit name | requests\_per\_min |
| limit | Integer | Yes | Limit value | 60 |
| remaining | Integer | Yes | Remaining available amount | 45 |
| reset\_seconds | Integer | Yes | Reset time (seconds) | 35 |
### Function Call Parameter Table [#function-call-parameter-table]
| Parameter | Type | Required | Description | Example Value |
| ----------- | ------ | -------- | ----------------------------- | ----------------------------------------- |
| type | String | Yes | Function type | function |
| name | String | Yes | Function name | get\_weather |
| description | String | No | Function description | Get the current weather |
| parameters | Object | Yes | Function parameter definition | \{"type": "object", "properties": \{...}} |
### Audio Format Parameter Table [#audio-format-parameter-table]
| Parameter | Type | Description | Optional Values |
| ----------------- | ------- | ------------------ | -------------------------------- |
| sample\_rate | Integer | Sample rate | 8000, 16000, 24000, 44100, 48000 |
| channels | Integer | Number of channels | 1 (mono), 2 (stereo) |
| bits\_per\_sample | Integer | Bits per sample | 16 (pcm16), 8 (g711) |
| encoding | String | Encoding method | pcm16, g711\_ulaw, g711\_alaw |
### Voice Detection Parameter Table [#voice-detection-parameter-table]
| Parameter | Type | Description | Default Value | Range |
| --------------------- | ------- | ----------------------------------------- | ------------- | --------- |
| threshold | Float | VAD activation threshold | 0.5 | 0.0-1.0 |
| prefix\_padding\_ms | Integer | Voice prefix padding (milliseconds) | 500 | 0-5000 |
| silence\_duration\_ms | Integer | Silence detection duration (milliseconds) | 1000 | 100-10000 |
### Tool Selection Parameter Table [#tool-selection-parameter-table]
| Parameter | Type | Description | Optional Values |
| ------------ | ------ | --------------------- | ----------------------------------------- |
| tool\_choice | String | Tool selection method | auto, none, required |
| tools | Array | Available tools list | \[\{type, name, description, parameters}] |
### Model Configuration Parameter Table [#model-configuration-parameter-table]
| Parameter | Type | Description | Range/Optional Values | Default Value |
| ------------------- | -------------- | --------------------- | --------------------- | ------------- |
| temperature | Float | Sampling temperature | 0.0-2.0 | 1.0 |
| max\_output\_tokens | Integer/String | Maximum output length | 1-4096/"inf" | "inf" |
| modalities | String array | Response modalities | \["text", "audio"] | \["text"] |
| voice | String | Voice type | alloy, echo, shimmer | alloy |
### Event Common Parameter Table [#event-common-parameter-table]
| Parameter | Type | Required | Description | Example Value |
| --------- | ------- | -------- | ------------------------------ | -------------- |
| event\_id | String | Yes | Unique identifier for event | event\_123 |
| type | String | Yes | Event type | session.update |
| timestamp | Integer | No | Event timestamp (milliseconds) | 1677649363000 |
### Session Status Parameter Table [#session-status-parameter-table]
| Parameter | Type | Description | Optional Values |
| --------- | ------ | ----------------- | ---------------------------------------------------- |
| status | String | Session status | active, ended, error |
| error | Object | Error information | \{"type": "error\_type", "message": "error message"} |
| metadata | Object | Session metadata | \{"client\_id": "web", "session\_type": "chat"} |
### Conversation Item Status Parameter Table [#conversation-item-status-parameter-table]
| Parameter | Type | Description | Optional Values |
| --------- | ------ | ------------------------ | ----------------------------------------------- |
| status | String | Conversation item status | completed, in\_progress, incomplete |
| role | String | Sender role | user, assistant, system |
| type | String | Conversation item type | message, function\_call, function\_call\_output |
### Content Type Parameter Table [#content-type-parameter-table]
| Parameter | Type | Description | Optional Values |
| --------- | ------ | --------------- | ----------------------- |
| type | String | Content type | text, audio, transcript |
| format | String | Content format | plain, markdown, html |
| encoding | String | Encoding method | utf-8, base64 |
### Response Status Parameter Table [#response-status-parameter-table]
| Parameter | Type | Description | Optional Values |
| --------------- | ------ | ---------------- | ----------------------------------------------------------------- |
| status | String | Response status | completed, cancelled, failed, incomplete |
| status\_details | Object | Status details | \{"reason": "user\_cancelled"} |
| usage | Object | Usage statistics | \{"total\_tokens": 50, "input\_tokens": 20, "output\_tokens": 30} |
### Audio Transcription Parameter Table [#audio-transcription-parameter-table]
| Parameter | Type | Description | Example Value |
| --------- | ------- | -------------------------------- | ------------------------------ |
| enabled | Boolean | Whether transcription is enabled | true |
| model | String | Transcription model | whisper-1 |
| language | String | Transcription language | en, zh, auto |
| prompt | String | Transcription prompt | "Transcript of a conversation" |
### Audio Stream Parameter Table [#audio-stream-parameter-table]
| Parameter | Type | Description | Optional Values |
| ----------- | ------- | ------------------------ | ------------------- |
| chunk\_size | Integer | Audio chunk size (bytes) | 1024, 2048, 4096 |
| latency | String | Latency mode | low, balanced, high |
| compression | String | Compression method | none, opus, mp3 |
### WebRTC Configuration Parameter Table [#webrtc-configuration-parameter-table]
| Parameter | Type | Description | Default Value |
| ------------------- | ------- | --------------------------------- | -------------------------------------------- |
| ice\_servers | Array | ICE server list | \[\{"urls": "stun:stun.l.google.com:19302"}] |
| audio\_constraints | Object | Audio constraints | \{"echoCancellation": true} |
| connection\_timeout | Integer | Connection timeout (milliseconds) | 30000 |
# OpenAI Response Format (Responses) (/en/api/openai-responses)
[OpenAI Responses](https://platform.openai.com/docs/api-reference/responses)
## 📝 Introduction [#-introduction]
OpenAI's most advanced model response interface. Supports text and image input, as well as text output. Create stateful interactions with the model, using the output of a previous response as input. Extend the model's capabilities using built-in tools such as file search, web search, and computer use. Use function calling to allow the model access to external systems and data.
Related guides can be found on the OpenAI official website: [Responses](https://platform.openai.com/docs/guides/migrate-to-responses)
## 💡 Request Examples [#-request-examples]
### Basic Text Response ✅ [#basic-text-response-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "讲一个三句话的关于独角兽的睡前故事。"
}'
```
**Response Example:**
```json
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"created_at": 1741476542,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "在一个宁静的月夜下，一只名叫璐米娜的独角兽发现了一个倒映着星星的隐藏水池。当她将独角浸入水中时，水池开始闪烁，显现出通往一个有着无尽夜空的魔法世界的路径。充满好奇，璐米娜为所有做梦的人许下愿望，希望他们能找到自己的隐藏魔法，当她回头望去，她的蹄印像星尘一样闪烁。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}
```
### Image Analysis Response ✅ [#image-analysis-response-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "描述这张图片中的内容"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
]
}
]
}'
```
**Response Example:**
```json
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"created_at": 1741476777,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "这张图片展示了一条木制栈道或小径穿过茂密的绿色草地，上方是点缀着几朵云的蓝天。场景呈现出一个宁静的自然区域，可能是公园或自然保护区。背景中有树木和灌木丛。整个景观展现出和谐的自然环境，栈道为游客提供了一条穿过湿地或草原而不影响周围生态系统的路径。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}
```
### Web Search Tool ✅ [#web-search-tool-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{ "type": "web_search_preview" }],
"input": "今天有什么积极正面的新闻?"
}'
```
**Response Example:**
```json
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"created_at": 1741484430,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "截至今天，2025年3月9日，一则值得关注的积极新闻是中国科学家在可再生能源领域取得重大突破，成功研发出一种新型高效太阳能电池，转化率达到了创纪录的35%，这可能会极大推动清洁能源的普及和应用。这项技术预计将使太阳能发电成本降低约40%，为全球减少碳排放提供了新的解决方案。",
"annotations": [
{
"type": "url_citation",
"start_index": 42,
"end_index": 100,
"url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
"title": "中国科学家在可再生能源领域取得重大突破"
},
{
"type": "url_citation",
"start_index": 101,
"end_index": 150,
"url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
"title": "新型高效太阳能电池转化率创纪录"
},
{
"type": "url_citation",
"start_index": 151,
"end_index": 200,
"url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
"title": "太阳能发电成本有望降低40%"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}
```
### File Search Tool ✅ [#file-search-tool-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "古代棕龙有哪些特性和属性?"
}'
```
**Response Example:**
```json
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"created_at": 1741485253,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": [
"古代棕龙的特性和属性"
],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "根据资料，古代棕龙具有以下特性和属性：\n\n1. 物理特征：古代棕龙体型庞大，体长可达25-30米，翼展约35米。它们的鳞片呈深棕色至铜色，随着年龄增长会变得更加暗沉。头部有特征性的双角和脊刺，下颚强壮，适合撕裂猎物。\n\n2. 能力：它们能喷吐强力的酸液，对目标造成严重腐蚀伤害。古代棕龙还拥有出色的掘地能力，常在沙漠或山地挖掘复杂的巢穴系统。\n\n3. 智力：被认为是龙族中最为狡猾和有耐心的品种，智力极高，精通多种语言，并具有复杂的战术思维。\n\n4. 栖息地：主要栖息在干旱的山地和沙漠地区，喜欢炎热干燥的环境。\n\n5. 宝藏：古代棕龙以其庞大的宝藏闻名，特别喜爱收集铜币、红宝石和火焰魔法物品。\n\n6. 寿命：是所有龙种中寿命最长的之一，可活2000-2500年，随着年龄增长其力量和魔法能力也会增强。\n\n7. 性格：极度领地意识强，性格暴躁易怒，对侵入者毫不留情，但也以其罕见的耐心著称，能为复仇等待几个世纪。",
"annotations": [
{
"type": "file_citation",
"index": 80,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 233,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 345,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 420,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 520,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 580,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 655,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 781,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": [
"vs_1234567890"
]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}
```
### Streaming Response ✅ [#streaming-response-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"instructions": "你是一个有帮助的助手。",
"input": "你好！",
"stream": true
}'
```
**Streaming Response Example:**
```
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"你好"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"！"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" 我"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"能"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"为"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"您"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"提供"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"什么"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"帮助"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"吗"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"？"}
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"你好！ 我能为您提供什么帮助吗？"}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}
```
### Function Calling ✅ [#function-calling-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "波士顿今天的天气如何？",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'
```
**Response Example:**
```json
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"created_at": 1741294021,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1-2025-04-14",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"波士顿, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "获取指定位置的当前天气",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"unit"
]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314
},
"user": null,
"metadata": {}
}
```
### Reasoning Capability ✅ [#reasoning-capability-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "o3-mini",
"input": "一只啄木鸟能啄多少木头?",
"reasoning": {
"effort": "high"
}
}'
```
**Response Example:**
```json
{
"id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
"object": "response",
"created_at": 1741477868,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "o1-2024-12-17",
"output": [
{
"type": "message",
"id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "这是一个源自英文绕口令"How much wood would a woodchuck chuck if a woodchuck could chuck wood"的问题。在现实中，啄木鸟(woodpecker)和土拨鼠(woodchuck)是不同的动物，而且土拨鼠实际上并不"啄(chuck)"木头。\n\n从科学角度看，啄木鸟每天确实会啄树木以寻找食物、建造巢穴或进行通讯。一只啄木鸟平均每天可能啄树约8000-12000次，视物种和具体目的而定。如果我们将这转换为木材量，假设每次啄击移除约0.1-0.2立方厘米的木材，那么一只啄木鸟理论上每天可能移除约800-2400立方厘米的木材。\n\n然而，啄木鸟主要是为了觅食和筑巢而啄木，而不是单纯地移除木材，所以这个计算只是一个有趣的理论估算。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": "high",
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 81,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 1035,
"output_tokens_details": {
"reasoning_tokens": 832
},
"total_tokens": 1116
},
"user": null,
"metadata": {}
}
```
## 📮 Request [#-request]
### Endpoint [#endpoint]
```
POST /v1/responses
```
Creates a model response. Provide text or image input to generate text or JSON output. Allow the model to call your own custom code or use built-in tools (such as web search or file search) to use your own data as input for the model response.
### Authentication Method [#authentication-method]
Include the following in the request header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
Where `$ZIPFLOW_API_KEY` is your API key.
### Request Body Parameters [#request-body-parameters]
#### input [#input]
**Type**: String or array\
**Required**: Yes
The text, image, or file input provided to the model to generate a response.
##### Possible Types [#possible-types]
| Type | Description |
| -------------------- | -------------------------------------------------------------------- |
| String | Text input, equivalent to text input with a user role |
| Array of input items | A list containing one or more input items of different content types |
##### Input Message Object [#input-message-object]
| Property | Type | Required | Description |
| -------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| content | String or array | Yes | The text, image, or audio input provided to the model to generate a response. Can also include previous assistant responses |
| role | String | Yes | The role of the input message. Possible values: `user`, `assistant`, `system`, or `developer` |
| type | String | No | The type of the input message, always `message` |
##### Content Item Types [#content-item-types]
###### Text Input [#text-input]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------- |
| text | String | Yes | The text input provided to the model |
| type | String | Yes | The type of the input item, always `input_text` |
###### Image Input [#image-input]
| Property | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| detail | String | Yes | The level of detail for the image to be sent to the model. Possible values: `high`, `low`, or `auto`. Defaults to `auto` |
| type | String | Yes | The type of the input item, always `input_image` |
| file\_id | String | No | The file ID to be sent to the model |
| image\_url | String | No | The image URL to be sent to the model. Can be a full URL or a base64 encoded image in a data URL |
###### File Input [#file-input]
| Property | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------- |
| type | String | Yes | The type of the input item, always `input_file` |
| file\_data | String | No | The file content to be sent to the model |
| file\_id | String | No | The file ID to be sent to the model |
| filename | String | No | The filename to be sent to the model |
##### Output Item Types [#output-item-types]
###### Output Text [#output-text]
| Property | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------- |
| text | String | Yes | The text output generated by the model |
| type | String | Yes | The type of the output item, always `output_text` |
| annotations | Array | Yes | Annotations for the text output |
###### Annotation Types [#annotation-types]
File Citation:
| Property | Type | Required | Description |
| -------- | ------- | -------- | ----------------------------------------------------- |
| file\_id | String | Yes | The ID of the file |
| index | Integer | Yes | The index of the file in the file list |
| type | String | Yes | The type of the file citation, always `file_citation` |
URL Citation:
| Property | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------------------------------------- |
| end\_index | Integer | Yes | The index of the last character of the URL citation in the message |
| start\_index | Integer | Yes | The index of the first character of the URL citation in the message |
| title | String | Yes | The title of the web resource |
| type | String | Yes | The type of the URL citation, always `url_citation` |
| url | String | Yes | The URL of the web resource |
File Path:
| Property | Type | Required | Description |
| -------- | ------- | -------- | --------------------------------------------- |
| file\_id | String | Yes | The ID of the file |
| index | Integer | Yes | The index of the file in the file list |
| type | String | Yes | The type of the file path, always `file_path` |
###### Refusal Response [#refusal-response]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------- |
| refusal | String | Yes | The model's explanation for refusal |
| type | String | Yes | The type of refusal, always `refusal` |
##### Tool Call Types [#tool-call-types]
###### File Search Tool Call [#file-search-tool-call]
| Property | Type | Required | Description |
| -------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| id | String | Yes | The unique ID for the file search tool call |
| queries | Array | Yes | Queries used to search files |
| status | String | Yes | The status of the file search tool call. Possible values include: `in_progress`, `searching`, `incomplete`, or `failed` |
| type | String | Yes | The type of the file search tool call, always `file_search_call` |
| results | Array or null | No | The results of the file search tool call |
###### Web Search Tool Call [#web-search-tool-call]
| Property | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| id | String | Yes | The unique ID for the web search tool call |
| status | String | Yes | The status of the web search tool call |
| type | String | Yes | The type of the web search tool call, always `web_search_call` |
###### Function Tool Call [#function-tool-call]
| Property | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| arguments | String | Yes | The JSON string of arguments passed to the function |
| call\_id | String | Yes | The unique ID of the function tool call generated by the model |
| name | String | Yes | The name of the function to run |
| type | String | Yes | The type of the function tool call, always `function_call` |
| id | String | No | The unique ID for the function tool call |
| status | String | No | The status of the item. Possible values: `in_progress`, `completed`, or `incomplete` |
###### Computer Tool Call [#computer-tool-call]
| Property | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| action | Object | Yes | The action for computer interaction, such as click, drag, etc. |
| call\_id | String | Yes | The identifier used when responding to the tool call output |
| id | String | Yes | The unique ID for the computer call |
| pending\_safety\_checks | Array | Yes | Pending safety checks for the computer call |
| status | String | Yes | The status of the item. Possible values: `in_progress`, `completed`, or `incomplete` |
| type | String | Yes | The type of the computer call, always `computer_call` |
Computer Action Types:
| Operation Type | Description |
| -------------- | ---------------------------- |
| click | Mouse click operation |
| double\_click | Mouse double click operation |
| drag | Drag operation |
| keypress | Key press operation |
| move | Mouse move operation |
| screenshot | Screenshot operation |
| scroll | Scroll operation |
| type | Text input operation |
| wait | Wait operation |
###### Computer Tool Call Output [#computer-tool-call-output]
| Property | Type | Required | Description |
| ---------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| call\_id | String | Yes | The ID of the computer tool call that produced the output |
| output | Object | Yes | The computer screenshot image used for the computer use tool |
| type | String | Yes | The type of the computer tool call output, always `computer_call_output` |
| acknowledged\_safety\_checks | Array | No | Safety checks reported by the API that have been acknowledged by the developer |
| id | String | No | The ID of the computer tool call output |
| status | String | No | The status of the input message. Possible values: `in_progress`, `completed`, or `incomplete` |
###### Function Tool Call Output [#function-tool-call-output]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| call\_id | String | Yes | The unique ID of the function tool call generated by the model |
| output | String | Yes | The JSON string of the function tool call output |
| type | String | Yes | The type of the function tool call output, always `function_call_output` |
| id | String | No | The unique ID for the function tool call output |
| status | String | No | The status of the item. Possible values: `in_progress`, `completed`, or `incomplete` |
##### Reasoning Related Items [#reasoning-related-items]
| Property | Type | Required | Description |
| ------------------ | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | Yes | The unique identifier for the reasoning content |
| summary | Array | Yes | Reasoning text content |
| type | String | Yes | The type of the object, always `reasoning` |
| encrypted\_content | String or null | No | Encrypted content of the reasoning item - populated when generating a response using the `reasoning.encrypted_content` include parameter |
| status | String | No | The status of the item. Possible values: `in_progress`, `completed`, or `incomplete` |
Reasoning Summary:
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------------------------------- |
| text | String | Yes | A brief summary of the reasoning used by the model when generating the response |
| type | String | Yes | The type of the object, always `summary_text` |
##### Item Reference [#item-reference]
| Property | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------------------------------- |
| id | String | Yes | The ID of the item to be referenced |
| type | String | No | The type of the item to be referenced, always `item_reference` |
#### model [#model]
**Type**: String\
**Required**: Yes
The model ID used to generate the response, such as gpt-4.1 or o3. OpenAI offers various models with different capabilities, performance characteristics, and price points. Please refer to the model guide to browse and compare available models.
#### include [#include]
**Type**: Array or null\
**Required**: No
Specifies additional output data to include in the model response. Current supported values include:
| Value | Description |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| `file_search_call.results` | Includes search results for file search tool calls |
| `message.input_image.image_url` | Includes the image URL in the input message |
| `computer_call_output.output.image_url` | Includes the image URL in the computer call output |
| `reasoning.encrypted_content` | Includes the encrypted version of reasoning tokens in the reasoning item output |
#### instructions [#instructions]
**Type**: String or null\
**Required**: No
Inserts a system (or developer) message as the first item in the model context.
When used with `previous_response_id`, instructions from the previous response are not carried over to the next response. This makes it simple to switch the system (developer) message in a new response.
#### max\_output\_tokens [#max_output_tokens]
**Type**: Integer or null\
**Required**: No
An upper bound on the number of tokens that can be generated for the response, including visible output tokens and reasoning tokens.
#### metadata [#metadata]
**Type**: Object\
**Required**: No
A collection of 16 key-value pairs that can be attached to an object. This is useful for storing additional information about the object in a structured format and can be queried via the API or dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
#### parallel\_tool\_calls [#parallel_tool_calls]
**Type**: Boolean or null\
**Required**: No\
**Default Value**: true
Whether the model is allowed to run tool calls in parallel.
#### previous\_response\_id [#previous_response_id]
**Type**: String or null\
**Required**: No
The unique ID of the model's previous response. Use this parameter to create multi-turn conversations. Learn more about conversation state.
#### reasoning [#reasoning]
**Type**: Object or null\
**Required**: No\
**Only applicable to o-series models**
Configuration options for the reasoning model.
| Property | Type | Required | Description |
| ----------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| effort | String or null | No | The degree of reasoning effort. Possible values: `low`, `medium`, `high`. Defaults to `medium`. Lowering reasoning effort can speed up the response and reduce the number of tokens used for reasoning in the response |
| summary | String or null | No | A summary of the reasoning performed by the model. This is useful for debugging and understanding the model's reasoning process. Possible values: `auto`, `concise`, `detailed` |
| generate\_summary | String or null | No | **Deprecated**: Please use `summary` instead. A summary of the reasoning performed by the model. Possible values: `auto`, `concise`, `detailed` |
#### service\_tier [#service_tier]
**Type**: String or null\
**Required**: No\
**Default Value**: auto
Specifies the latency tier used to process the request. This parameter is relevant for customers subscribed to the scale tier service:
| Value | Description |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | If the project has Scale tier enabled, the system will use Scale tier credits until exhausted; if the project does not have Scale tier enabled, the request will be processed using the default service tier, which has a lower uptime SLA and no latency guarantee |
| `default` | The request will be processed using the default service tier, which has a lower uptime SLA and no latency guarantee |
| `flex` | The request will be processed using the Flex Processing service tier. Learn more in the official documentation |
When this parameter is not set, the default behavior is `auto`.
When this parameter is set, the response body will include the `service_tier` used.
#### store [#store]
**Type**: Boolean or null\
**Required**: No\
**Default Value**: true
Whether to store the generated model response for later retrieval via the API.
#### stream [#stream]
**Type**: Boolean or null\
**Required**: No\
**Default Value**: false
If set to true, the model response data will be streamed to the client using Server-Sent Events as it is generated.
#### temperature [#temperature]
**Type**: Number or null\
**Required**: No\
**Default Value**: 1
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this value or `top_p` but not both.
#### text [#text]
**Type**: Object\
**Required**: No
Configuration options for the model's text response. Can be plain text or structured JSON data.
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------ |
| format | Object | No | Specifies the format the model must output |
Configuring `{ "type": "json_schema" }` enables structured output, ensuring the model will match the JSON schema you provide. See the Structured Output guide for more information.
The default format is `{ "type": "text" }`, with no other options.
**Not recommended for gpt-4o and newer models**:
Setting to `{ "type": "json_object" }` enables the older JSON mode, ensuring the model generates a valid JSON message. For supported models, `json_schema` is preferred.
##### Text Format Types [#text-format-types]
###### Text (Text) [#text-text]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------- |
| type | String | Yes | The defined response format type. Always `text` |
###### JSON Schema (JSON Schema) [#json-schema-json-schema]
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | String | Yes | The name of the response format. Must contain a-z, A-Z, 0-9, or include underscores and dashes, maximum length 64 |
| schema | Object | Yes | The schema for the response format, described as a JSON Schema object |
| type | String | Yes | The defined response format type. Always `json_schema` |
| description | String | No | A description of the response format's purpose, which the model uses to determine how to respond in that format |
| strict | Boolean or null | No | Whether to enable strict mode adherence when generating output. Defaults to `false`. If set to `true`, the model will strictly follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported in strict mode |
###### JSON Object (JSON Object) [#json-object-json-object]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------------ |
| type | String | Yes | The defined response format type. Always `json_object` |
Note: The model will not generate JSON unless instructed to do so by a system or user message. For supported models, `json_schema` is recommended.
#### tool\_choice [#tool_choice]
**Type**: String or object\
**Required**: No
How the model selects the tool (or tools) to use when generating a response. See the `tools` parameter for how to specify tools the model can call.
##### Possible Types [#possible-types-1]
###### Tool choice mode (Tool choice mode) [#tool-choice-mode-tool-choice-mode]
**Type**: String
Controls whether and which tool the model calls.
| Value | Description |
| ---------- | ------------------------------------------------------------------------------ |
| `none` | The model will not call any tools, but instead generate a message |
| `auto` | The model can choose between generating a message or calling one or more tools |
| `required` | The model must call one or more tools |
###### Hosted tool (Hosted tool) [#hosted-tool-hosted-tool]
**Type**: Object
Instructs the model to use a built-in tool to generate a response.
| Property | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| type | String | Yes | The type of hosted tool the model should use. Allowed values are: `file_search`, `web_search_preview`, `computer_use_preview` |
###### Function tool (Function tool) [#function-tool-function-tool]
**Type**: Object
Use this option to force the model to call a specific function.
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------------- |
| name | String | Yes | The name of the function to call |
| type | String | Yes | For function calls, the type is always `function` |
#### tools [#tools]
**Type**: Array\
**Required**: No
An array of tools the model may call when generating a response. You can specify which tool to use by setting the `tool_choice` parameter.
The two categories of tools you can provide to the model are:
* **Built-in tools**: Tools provided by OpenAI to extend model capabilities, such as web search or file search.
* **Function calling (custom tools)**: Functions defined by you, enabling the model to call your own code.
##### File search tool (File search) [#file-search-tool-file-search]
**Type**: Object
A tool that searches for relevant content within uploaded files.
| Property | Type | Required | Description |
| ------------------ | ------- | -------- | ------------------------------------------------------------------------------------------- |
| type | String | Yes | The type of the file search tool, always `file_search` |
| vector\_store\_ids | Array | Yes | A list of vector store IDs to search |
| filters | Object | No | Filters to apply |
| max\_num\_results | Integer | No | The maximum number of results to return. This number should be between 1 and 50 (inclusive) |
| ranking\_options | Object | No | Search ranking options |
###### Filter Types [#filter-types]
**Comparison Filter (Comparison Filter)**
| Property | Type | Required | Description |
| -------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | String | Yes | The key to compare against the value |
| type | String | Yes | Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`
- eq: equals
- ne: not equals
- gt: greater than
- gte: greater than or equals
- lt: less than
- lte: less than or equals |
| value | String/Number/Boolean | Yes | The value to compare against the property key; supports string, number, or boolean types |
**Compound Filter (Compound Filter)**
| Property | Type | Required | Description |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| filters | Array | Yes | An array of filters to combine. Items can be comparison filters or compound filters |
| type | String | Yes | The operation type: `and` or `or` |
###### Ranking Options [#ranking-options]
| Property | Type | Required | Description |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ranker | String | No | The ranker used for file search |
| score\_threshold | Number | No | The score threshold for file search, a number between 0 and 1. A number close to 1 will attempt to return only the most relevant results but may return fewer results |
##### Function tool (Function) [#function-tool-function]
**Type**: Object
Defines a function in your own code that the model can choose to call.
| Property | Type | Required | Description |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| type | String | Yes | The type of the function tool, always `function` |
| name | String | Yes | The name of the function to call |
| parameters | Object | Yes | A JSON schema object describing the function parameters |
| strict | Boolean | Yes | Whether to enforce strict parameter validation. Defaults to `true` |
| description | String | No | A description of the function. The model uses this to determine whether to call the function |
##### Web search tool (Web search preview) [#web-search-tool-web-search-preview]
**Type**: Object
This tool searches the web for relevant results to use in the response.
| Property | Type | Required | Description |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| type | String | Yes | The type of the web search tool. Possible values: `web_search_preview` or `web_search_preview_2025_03_11` |
| search\_context\_size | String | No | High-level guidance on the amount of context window space to use for searching. Possible values: `low`, `medium`, `high`. Defaults to `medium` |
| user\_location | Object | No | User's location |
| domains | Array | No | A list of domains to restrict the search to |
###### User Location [#user-location]
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------------- |
| type | String | Yes | Location approximation type. Always `approximate` |
| city | String | No | Free text input for the user's city, e.g., "San Francisco" |
| country | String | No | The user's two-letter ISO country code, e.g., "US" |
| region | String | No | Free text input for the user's region, e.g., "California" |
| timezone | String | No | The user's IANA timezone, e.g., "America/Los\_Angeles" |
##### Computer use tool (Computer use preview) [#computer-use-tool-computer-use-preview]
**Type**: Object
A tool for controlling a virtual computer.
| Property | Type | Required | Description |
| --------------- | ------- | -------- | ---------------------------------------------------------------- |
| type | String | Yes | The type of the computer use tool. Always `computer_use_preview` |
| display\_height | Integer | Yes | The height of the computer display |
| display\_width | Integer | Yes | The width of the computer display |
| environment | String | Yes | The type of computer environment to control |
#### top\_p [#top_p]
**Type**: Number or null\
**Required**: No\
**Default Value**: 1
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of tokens with the top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this value or `temperature` but not both.
#### truncation [#truncation]
**Type**: String or null\
**Required**: No\
**Default Value**: disabled
Truncation policy used for model responses:
| Value | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` | If the context of this response and the previous response exceeds the model's context window size, the model will truncate the response by removing input items in the middle of the conversation to fit the context window |
| `disabled` | If the model response would exceed the model's context window size, the request will fail with a 400 error |
#### user [#user]
**Type**: String\
**Required**: No
A unique identifier representing the end-user, which can help OpenAI to monitor and detect abuse.
## 📥 Response [#-response]
Returns a response object.
### Successful Response [#successful-response]
Returns a response object, or a streaming sequence of response objects if the request was streamed.
#### id [#id]
* Type: String
* Description: The unique identifier for the response
#### object [#object]
* Type: String
* Description: Object type, value is "response"
#### created\_at [#created_at]
* Type: Integer
* Description: Timestamp of when the response was created
#### status [#status]
* Type: String
* Description: Response status, such as "completed", "in\_progress", etc.
#### error [#error]
* Type: Object or null
* Description: Contains error information if an error occurred
#### incomplete\_details [#incomplete_details]
* Type: Object or null
* Description: Contains detailed information if the response is incomplete
#### instructions [#instructions-1]
* Type: String or null
* Description: System instructions provided to the model
#### max\_output\_tokens [#max_output_tokens-1]
* Type: Integer or null
* Description: Maximum number of output tokens
#### model [#model-1]
* Type: String
* Description: Name of the model used
#### output [#output]
* Type: Array
* Description: Contains the generated reply and tool calls
* Possible contents:
* Message object (`type`: "message")
* Tool use object (`type`: "tool\_use")
#### parallel\_tool\_calls [#parallel_tool_calls-1]
* Type: Boolean
* Description: Whether parallel tool calls are enabled
#### previous\_response\_id [#previous_response_id-1]
* Type: String or null
* Description: ID of the previous response (used for multi-turn conversations)
#### reasoning [#reasoning-1]
* Type: Object
* Description: Reasoning related information
#### store [#store-1]
* Type: Boolean
* Description: Whether this response is stored
#### temperature [#temperature-1]
* Type: Number
* Description: Sampling temperature used
#### text [#text-1]
* Type: Object
* Description: Text output format configuration
#### tool\_choice [#tool_choice-1]
* Type: String
* Description: Tool choice strategy
#### tools [#tools-1]
* Type: Array
* Description: List of available tools
#### top\_p [#top_p-1]
* Type: Number
* Description: Nucleus sampling threshold
#### truncation [#truncation-1]
* Type: String
* Description: Truncation policy
#### usage [#usage]
* Type: Object
* Description: Token usage statistics
* Properties:
* `input_tokens`: Number of tokens used for input
* `input_tokens_details`: Input token details
* `output_tokens`: Number of tokens used for output
* `output_tokens_details`: Output token details
* `total_tokens`: Total number of tokens
#### user [#user-1]
* Type: String or null
* Description: User identifier
#### metadata [#metadata-1]
* Type: Object
* Description: Additional metadata information
# OpenAI Video Format (Sora Format) (/en/api/openai-video)
Generate videos by calling the OpenAI video generation interface, supporting models like Sora, and also supporting the use of the OpenAI video format to call Kling, Jimeng, and Vidu.
## Generate Video [#generate-video]
### API Endpoint [#api-endpoint]
```
POST /v1/videos
```
### Request Headers [#request-headers]
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------- |
| Authorization | string | Yes | User Authentication Token (Bearer: sk-xxxx) |
### Request Parameters (multipart/form-data) [#request-parameters-multipartform-data]
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| prompt | string | Yes | Text prompt describing the video to be generated |
| model | string | No | Video generation model, defaults to sora-2 |
| seconds | string | No | Video duration (seconds), defaults to 4 seconds |
| size | string | No | Output resolution, format is width x height, defaults to 720x1280 |
| input\_reference | file | No | Input image file (used for Image-to-Video), the input image must match the corresponding width and height (size) |
| metadata | string | No | Extended parameters (JSON string format) |
#### metadata Parameter Description [#metadata-parameter-description]
The purpose of the metadata parameter is to pass parameters specific to non-Sora models, such as Aliyun Wanxiang's image URL, watermark, and prompt intelligent rewriting. The format of the metadata parameter is a JSON string, for example:
```json
{
"img_url": "https://example.com/image.jpg",
"watermark": false,
"prompt_extend": true
}
```
### Request Examples [#request-examples]
#### Text-to-Video (Text Prompt Only) [#text-to-video-text-prompt-only]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级" \
-F "model=sora-2" \
-F "seconds=5" \
-F "size=1920x1080"
```
#### Image-to-Video (Text Prompt + Image File) [#image-to-video-text-prompt--image-file]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=猫咪慢慢睁开眼睛，伸懒腰" \
-F "model=sora-2" \
-F "seconds=3" \
-F "size=1920x1080" \
-F "input_reference=@/path/to/cat.jpg"
```
#### Aliyun Wanxiang Video Generation Example [#aliyun-wanxiang-video-generation-example]
##### Text-to-Video (Wanxiang 2.5) [#text-to-video-wanxiang-25]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=一只可爱的小猫在花园里玩耍，阳光明媚，色彩鲜艳" \
-F "model=wan2.5-t2v-preview" \
-F "seconds=5" \
-F "size=1920*1080"
```
##### Image-to-Video (Wanxiang 2.5) [#image-to-video-wanxiang-25]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=让这张图片动起来，添加自然的运动效果" \
-F "model=wan2.5-i2v-preview" \
-F "seconds=5" \
-F "size=1280P" \
-F 'metadata={"img_url":"https://example.com/image.jpg"}'
```
### Response Format [#response-format]
#### 201 - Created Successfully [#201---created-successfully]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "processing",
"progress": 0
}
```
#### Response Field Description [#response-field-description]
| Field | Type | Description |
| ----------- | ------- | ------------------------------------- |
| id | string | Video Task ID |
| object | string | Object type, fixed as "video" |
| model | string | Name of the model used |
| created\_at | integer | Creation timestamp |
| status | string | Task status (processing: in progress) |
| progress | integer | Generation progress percentage |
## Query Video [#query-video]
Query the status and result of the video generation task based on the Task ID
### API Endpoint [#api-endpoint-1]
```
GET /v1/videos/{video_id}
```
### Path Parameters [#path-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------- |
| video\_id | string | Yes | Video Task ID |
### Request Example [#request-example]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### Response Format [#response-format-1]
#### 200 - Successful Response [#200---successful-response]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard"
}
```
#### Response Field Description [#response-field-description-1]
| Field | Type | Description |
| ----------- | ------- | ---------------------------------------------------------------------------- |
| id | string | Video Task ID |
| object | string | Object type, fixed as "video" |
| model | string | Name of the model used |
| created\_at | integer | Creation timestamp |
| status | string | Task status (processing: in progress, succeeded: successful, failed: failed) |
| progress | integer | Generation progress percentage |
| expires\_at | integer | Resource expiration timestamp |
| size | string | Video resolution |
| seconds | string | Video duration (seconds) |
| quality | string | Video quality |
| url | string | Video download link (upon completion) |
## Get Video Task Status [#get-video-task-status]
Retrieve detailed information about the video generation task based on the Task ID
### API Endpoint [#api-endpoint-2]
```
GET /v1/videos/{video_id}
```
### Path Parameters [#path-parameters-1]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| video\_id | string | Yes | Identifier of the video task to retrieve |
### Request Example [#request-example-1]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### Response Format [#response-format-2]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard",
"remixed_from_video_id": null,
"error": null
}
```
#### Response Field Description [#response-field-description-2]
| Field | Type | Description |
| ------------------------ | ------- | ----------------------------------------------------------------------- |
| id | string | Unique identifier for the video task |
| object | string | Object type, fixed as "video" |
| model | string | Name of the model generating the video |
| status | string | Current lifecycle status of the video task |
| progress | integer | Approximate completion percentage of the generation task |
| created\_at | integer | Unix timestamp (seconds) when the task was created |
| expires\_at | integer | Unix timestamp (seconds) when the downloadable resource expires, if set |
| size | string | Resolution of the generated video |
| seconds | string | Duration (seconds) of the generated video clip |
| quality | string | Video quality |
| remixed\_from\_video\_id | string | Identifier of the source video if this video is a remix |
| error | object | Object containing error information if generation failed |
## Get Video Content [#get-video-content]
Download the completed video content
### API Endpoint [#api-endpoint-3]
```
GET /v1/videos/{video_id}/content
```
### Path Parameters [#path-parameters-2]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------- |
| video\_id | string | Yes | Identifier of the video to download |
### Query Parameters [#query-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------- |
| variant | string | No | Type of downloadable resource to return, defaults to MP4 video |
### Request Example [#request-example-2]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123/content' \
-H "Authorization: Bearer sk-xxxx" \
-o "video.mp4"
```
### Response Description [#response-description]
Directly returns the video file stream, Content-Type is `video/mp4`
#### Response Headers [#response-headers]
| Field | Description |
| ------------------- | ---------------------------------- |
| Content-Type | Video file type, usually video/mp4 |
| Content-Length | Video file size (bytes) |
| Content-Disposition | File download information |
## Error Responses [#error-responses]
### 400 - Request Parameter Error [#400---request-parameter-error]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 401 - Unauthorized [#401---unauthorized]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 403 - No Permission [#403---no-permission]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 404 - Task Does Not Exist [#404---task-does-not-exist]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 500 - Internal Server Error [#500---internal-server-error]
```json
{
"error": {
"message": "string",
"type": "server_error"
}
}
```
## Supported Models [#supported-models]
### OpenAI Compatible [#openai-compatible]
* `sora-2`: Sora video generation model
### Other Services Called via OpenAI Format [#other-services-called-via-openai-format]
* Aliyun Wanxiang (Ali Wan): Uses `wan2.5-t2v-preview` (Text-to-Video), `wan2.5-i2v-preview` (Image-to-Video), `wan2.2-i2v-flash`, `wan2.2-i2v-plus`, `wanx2.1-i2v-plus`, `wanx2.1-i2v-turbo`
* Kling AI (Kling): Uses `kling-v1`, `kling-v2-master`
* Jimeng: Uses `jimeng_vgfm_t2v_l20`, `jimeng_vgfm_i2v_l20`
* Vidu: Uses `viduq1`
## Aliyun Wanxiang Special Instructions [#aliyun-wanxiang-special-instructions]
### Supported Features [#supported-features]
* **Text-to-Video (t2v)**: Generates video using only a text prompt
* **Image-to-Video (i2v)**: Generates video using a text prompt + image
* **Keyframe-to-Video (kf2v)**: Generates video by specifying the first and last frame images
* **Audio Generation (s2v)**: Supports combining audio with video
### Resolution Support [#resolution-support]
* **480P**: 832×480, 480×832, 624×624
* **720P**: 1280×720, 720×1280, 960×960, 1088×832, 832×1088
* **1080P**: 1920×1080, 1080×1920, 1440×1440, 1632×1248, 1248×1632
### Special Parameters [#special-parameters]
* `watermark`: Whether to add a watermark (default false)
* `prompt_extend`: Whether to enable prompt intelligent rewriting (default true)
* `audio`: Whether to add audio (only supported by wan2.5)
* `seed`: Random seed
### Model Characteristics [#model-characteristics]
* **wan2.5-i2v-preview**: Wanxiang 2.5 preview version, supports video with sound, recommended
* **wan2.2-i2v-flash**: Wanxiang 2.2 Flash version, fast generation speed, silent video
* **wan2.2-i2v-plus**: Wanxiang 2.2 Pro version, higher image quality, silent video
* **wanx2.1-i2v-plus**: Wanxiang 2.1 Pro version, stable version
* **wanx2.1-i2v-turbo**: Wanxiang 2.1 Turbo version
## Best Practices [#best-practices]
1. **Request Format**: Use `multipart/form-data` format, which is the official OpenAI recommended method
2. **input\_reference Parameter**: Used for Image-to-Video functionality, use the `@filename` syntax when uploading an image file
3. **Prompt Optimization**: Use detailed and specific descriptive words, including style and quality requirements
4. **Parameter Settings**: Set duration and resolution reasonably according to requirements
5. **Aliyun Wanxiang Special Instructions**:
* **Direct file upload is not supported**, all resources are passed via URL
* Use the `metadata` parameter to pass all extended parameters (JSON string format)
* Image-to-Video uses `metadata.img_url` to pass the image URL
* Keyframe-to-Video uses `metadata.first_frame_url` and `metadata.last_frame_url`
6. **Error Handling**: Implement appropriate retry mechanisms and error handling
7. **Asynchronous Processing**: Video generation is an asynchronous task, requiring polling for status checks
8. **Resource Management**: Download and clean up unnecessary video files promptly
## JavaScript Example [#javascript-example]
### Using FormData (Recommended) [#using-formdata-recommended]
```javascript
async function generateVideoWithFormData() {
const formData = new FormData();
formData.append('prompt', '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级');
formData.append('model', 'sora-2');
formData.append('seconds', '5');
formData.append('size', '1920x1080');
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// Image-to-Video Example
async function generateVideoWithImage() {
const formData = new FormData();
formData.append('prompt', '猫咪慢慢睁开眼睛，伸懒腰');
formData.append('model', 'sora-2');
formData.append('seconds', '3');
formData.append('size', '1920x1080');
// 添加图片文件
const imageFile = document.getElementById('imageInput').files[0];
formData.append('input_reference', imageFile);
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
```
### Aliyun Wanxiang Calling Example [#aliyun-wanxiang-calling-example]
```javascript
// Aliyun Wanxiang Text-to-Video
async function generateAliVideo() {
const formData = new FormData();
formData.append('prompt', '一只可爱的小猫在花园里玩耍，阳光明媚，色彩鲜艳');
formData.append('model', 'wan2.5-t2v-preview');
formData.append('seconds', '5');
formData.append('size', '1920*1080');
formData.append('metadata', JSON.stringify({
watermark: false,
prompt_extend: true
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// Aliyun Wanxiang Image-to-Video
async function generateAliImageToVideo() {
const formData = new FormData();
formData.append('prompt', '让这张图片动起来，添加自然的运动效果');
formData.append('model', 'wan2.5-i2v-preview');
formData.append('seconds', '3');
formData.append('resolution', '720P');
formData.append('input_reference', imageFile);
formData.append('metadata', JSON.stringify({
watermark: false,
prompt_extend: true
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// Aliyun Wanxiang Keyframe-to-Video
async function generateAliKeyframeVideo() {
const formData = new FormData();
formData.append('prompt', '从开始到结束的平滑过渡动画');
formData.append('model', 'wan2.2-kf2v-flash');
formData.append('seconds', '4');
formData.append('metadata', JSON.stringify({
first_frame_url: 'https://example.com/start.jpg',
last_frame_url: 'https://example.com/end.jpg',
resolution: '720P',
watermark: false
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
```
# Query Video API (/en/api/query-video)
Query the status and results of a video generation task based on the Task ID.
## Query Video Status [#query-video-status]
### API Endpoint [#api-endpoint]
```
GET /v1/video/generations/{task_id}
```
### Path Parameters [#path-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| task\_id | string | Yes | Task ID |
### Request Example [#request-example]
```bash
curl 'https://api.zipflow.xyz/v1/video/generations/{task_id}' \
-H "Authorization: Bearer sk-xxxx"
```
### Response Format [#response-format]
#### 200 - Success Response [#200---success-response]
```json
{
"error": null,
"format": "mp4",
"metadata": {
"duration": 5,
"fps": 30,
"height": 512,
"seed": 20231234,
"width": 512
},
"status": "succeeded",
"task_id": "abcd1234efgh",
"url": "https://example.com/video.mp4"
}
```
#### Response Field Description [#response-field-description]
| Field | Type | Description |
| -------- | ------ | ------------------------------------------------------------------------- |
| task\_id | string | Task ID |
| status | string | Task status (processing: processing, succeeded: success, failed: failure) |
| format | string | Video format |
| url | string | Video resource URL (on success) |
| metadata | object | Result metadata |
| error | object | Error information (null on success) |
### Status Description [#status-description]
| Status | Description |
| ------------ | -------------------------------------- |
| processing | The task is currently being processed |
| queued | The task is queued awaiting processing |
| in\_progress | The task is in progress |
| succeeded | The task completed successfully |
| failed | The task failed |
## OpenAI Compatible Format Query [#openai-compatible-format-query]
### API Endpoint [#api-endpoint-1]
```
GET /v1/videos/{video_id}
```
### Path Parameters [#path-parameters-1]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------- |
| video\_id | string | Yes | Video Task ID |
### Request Example [#request-example-1]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### Response Format [#response-format-1]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard",
"url": "https://example.com/video.mp4"
}
```
#### Response Field Description [#response-field-description-1]
| Field | Type | Description |
| ----------- | ------- | ----------------------------------------------------------------------- |
| id | string | Unique identifier for the video task |
| object | string | Object type, fixed as "video" |
| model | string | Name of the model that generated the video |
| status | string | Current lifecycle status of the video task |
| progress | integer | Approximate completion percentage of the generation task |
| created\_at | integer | Unix timestamp (seconds) when the task was created |
| expires\_at | integer | Unix timestamp (seconds) when the downloadable resource expires, if set |
| size | string | Resolution of the generated video |
| seconds | string | Duration of the generated video clip (seconds) |
| quality | string | Video quality |
| url | string | Video download link (upon completion) |
## Retrieve Video Content [#retrieve-video-content]
### API Endpoint [#api-endpoint-2]
```
GET /v1/videos/{video_id}/content
```
### Path Parameters [#path-parameters-2]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------- |
| video\_id | string | Yes | Identifier of the video to download |
### Query Parameters [#query-parameters]
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------ |
| variant | string | No | The type of downloadable resource to return, defaults to MP4 video |
### Request Example [#request-example-2]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123/content' \
-H "Authorization: Bearer sk-xxxx" \
-o "video.mp4"
```
### Response Description [#response-description]
Directly returns the video file stream, with Content-Type as `video/mp4`
#### Response Headers [#response-headers]
| Field | Description |
| ------------------- | ---------------------------------- |
| Content-Type | Video file type, usually video/mp4 |
| Content-Length | Video file size (bytes) |
| Content-Disposition | File download information |
## Error Responses [#error-responses]
### 400 - Invalid Request Parameters [#400---invalid-request-parameters]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - Unauthorized [#401---unauthorized]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - Forbidden [#403---forbidden]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 404 - Task Not Found [#404---task-not-found]
```json
{
"code": null,
"message": "Task not found",
"param": "task_id",
"type": "invalid_request_error"
}
```
### 500 - Internal Server Error [#500---internal-server-error]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
## Polling Strategy [#polling-strategy]
### Recommended Polling Intervals [#recommended-polling-intervals]
1. **Initial Polling**: Wait 2-3 seconds after submitting the task before starting to poll.
2. **Polling Frequency**:
* First 30 seconds: Poll once every 5 seconds.
* 30 seconds to 2 minutes: Poll once every 10 seconds.
* After 2 minutes: Poll once every 30 seconds.
3. **Timeout Handling**: It is recommended to set a total timeout of 5-10 minutes.
### Polling Example Code [#polling-example-code]
```javascript
async function pollVideoStatus(taskId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/video/generations/${taskId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`Video generation failed: ${result.error?.message || 'Unknown error'}`);
}
// 等待后重试
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('Max polling attempts reached');
}
```
## Best Practices [#best-practices]
1. **Status Check**: Regularly check the task status to avoid overly frequent requests.
2. **Error Handling**: Properly handle various error conditions, including network errors and API errors.
3. **Timeout Setting**: Set a reasonable timeout period to avoid infinite waiting.
4. **Caching Strategy**: Consider caching results for completed videos.
5. **Concurrency Control**: Avoid initiating too many query requests simultaneously.
6. **Resource Cleanup**: Download and promptly clean up unnecessary video files.
# Suno Music Format (Music) (/en/api/suno-music)
This interface is **not an official Suno interface**, but rather a Suno proxy interface implemented based on the open-source project [**Suno-API**](https://github.com/Suno-API/Suno-API) by author **Plato**.
We are very grateful for the author's contribution, which allows us to easily use Suno's powerful features. If you have time, please give the author a Star.
## 📝 Introduction [#-introduction]
Suno Music API provides a series of music generation and processing functions, including:
* Generate songs based on prompts (Inspiration mode, Custom mode)
* Continue writing existing songs
* Concatenate multiple audio segments
* Generate lyrics
* Upload audio
Through the API, you can easily integrate AI music generation capabilities into your applications.
## 💡 Request Examples [#-request-examples]
### Generate Song ✅ [#generate-song-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/music' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"prompt":"[Verse]\nWalking down the streets\nBeneath the city lights\nNeon signs flickering\nLighting up the night\nHeart beating faster\nLike a drum in my chest\nI'\''m alive in this moment\nFeeling so blessed\n\nStilettos on the pavement\nStepping with grace\nSurrounded by the people\nMoving at their own pace\nThe rhythm of the city\nIt pulses in my veins\nLost in the energy\nAs my worries drain\n\n[Verse 2]\nConcrete jungle shining\nWith its dazzling glow\nEvery corner hiding secrets that only locals know\nA symphony of chaos\nBut it'\''s music to my ears\nThe hustle and the bustle\nWiping away my fears",
"tags":"emotional punk",
"mv":"chirp-v4",
"title":"City Lights"
}'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### Generate Lyrics ✅ [#generate-lyrics-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/lyrics' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"prompt":"dance"
}'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### Upload Audio ❌ [#upload-audio-]
```bash
curl --location 'https://api.zipflow.xyz/suno/uploads/audio-url' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url":"http://cdnimg.example.com/ai/2024-06-18/d416d9c3c34eb22c7d8c094831d8dbd0.mp3"
}'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### Song Concatenation ❌ [#song-concatenation-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/concat' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"clip_id":"extend song ID",
"is_infill": false
}'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### Query Task Status ✅ [#query-task-status-]
#### Batch Query [#batch-query]
```bash
curl --location 'https://api.zipflow.xyz/suno/fetch' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"ids":["task_id"],
"action":"MUSIC"
}'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":[
{
"task_id":"346c5d10-a4a1-4f49-a851-66a7dae6cfaf",
"notify_hook":"",
"action":"MUSIC",
"status":"IN_PROGRESS",
"fail_reason":"",
"submit_time":1716191749,
"start_time":1716191786,
"finish_time":0,
"progress":"0%",
"data":[
{
"id":"e9893d04-6a63-4007-8473-64b706eca4d1",
"title":"Electric Dance Party",
"status":"streaming",
"metadata":{
"tags":"club banger high-energy edm",
"prompt":"omitted",
"duration":null,
"error_type":null,
"error_message":null,
"audio_prompt_id":null,
"gpt_description_prompt":"miku dance"
},
"audio_url":"https://audiopipe.suno.ai/?item_id=e9893d04-6a63-4007-8473-64b706eca4d1",
"image_url":"https://cdn1.suno.ai/image_e9893d04-6a63-4007-8473-64b706eca4d1.png",
"video_url":"",
"model_name":"chirp-v3",
"image_large_url":"https://cdn1.suno.ai/image_large_e9893d04-6a63-4007-8473-64b706eca4d1.png",
"major_model_version":"v3"
}
]
}
]
}
```
#### Single Query [#single-query]
```bash
curl --location 'https://api.zipflow.xyz/suno/fetch/{{task_id}}' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY'
```
**Response Example:**
```json
{
"code":"success",
"message":"",
"data":{
"task_id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
"notify_hook":"",
"action":"LYRICS",
"status":"SUCCESS",
"fail_reason":"",
"submit_time":1716192124,
"start_time":1716192124,
"finish_time":1716192124,
"progress":"100%",
"data":{
"id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
"text":"omitted",
"title":"Electric Fantasy",
"status":"complete"
}
}
}
```
## 📮 Request [#-request]
All requests must include authentication information in the request header:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
### Endpoints [#endpoints]
#### Generate Song [#generate-song]
```
POST /suno/submit/music
```
Generate new songs, supporting inspiration mode, custom mode, and continuation.
#### Generate Lyrics [#generate-lyrics]
```
POST /suno/submit/lyrics
```
Generate lyrics based on prompts.
#### Upload Audio [#upload-audio]
```
POST /suno/uploads/audio-url
```
Upload audio files.
#### Song Concatenation [#song-concatenation]
```
POST /suno/submit/concat
```
Concatenate multiple audio segments into a complete song.
#### Batch Query Task Status [#batch-query-task-status]
```
POST /suno/fetch
```
Batch get the status and results of multiple tasks.
#### Query Single Task Status [#query-single-task-status]
```
GET /suno/fetch/{{task_id}}
```
Query the status and results of a single task.
### Request Body Parameters [#request-body-parameters]
#### Generate Song [#generate-song-1]
##### `prompt` [#prompt]
* Type:String
* Required:Inspiration mode does not require, custom mode requires
* Description:Lyric content, needs to be provided in custom mode
##### `mv` [#mv]
* Type:String
* Required:No
* Description:Model version, optional values: chirp-v3-0, chirp-v3-5, default is chirp-v3-0
##### `title` [#title]
* Type:String
* Required:Inspiration mode does not require, custom mode requires
* Description:Song title, needs to be provided in custom mode
##### `tags` [#tags]
* Type:String
* Required:Inspiration mode does not require, custom mode requires
* Description:Song style tags, separated by commas, needs to be provided in custom mode
##### `make_instrumental` [#make_instrumental]
* Type:Boolean
* Required:No
* Description:Whether to generate pure music, true means generate pure music
##### `task_id` [#task_id]
* Type:String
* Required:Required when continuing
* Description:The task ID of the song to be continued
##### `continue_at` [#continue_at]
* Type:Float
* Required:Required when continuing
* Description:Continue writing from which second of the song
##### `continue_clip_id` [#continue_clip_id]
* Type:String
* Required:Required when continuing
* Description:The clip ID of the song to be continued
##### `gpt_description_prompt` [#gpt_description_prompt]
* Type:String
* Required:Required in inspiration mode, not required in other modes
* Description:Text description of the source of inspiration
##### `notify_hook` [#notify_hook]
* Type:String
* Required:No
* Description:Callback address for song generation completion
#### Generate Lyrics [#generate-lyrics-1]
##### `prompt` [#prompt-1]
* Type:String
* Required:Yes
* Description:Thematic or keyword of lyrics
##### `notify_hook` [#notify_hook-1]
* Type:String
* Required:No
* Description:Callback address for lyric generation completion
#### Upload Audio [#upload-audio-1]
##### `url` [#url]
* Type:String
* Required:Yes
* Description:URL address of the audio file to be uploaded
#### Song Concatenation [#song-concatenation-1]
##### `clip_id` [#clip_id]
* Type:String
* Required:Yes
* Description:ID of the song segment to be concatenated
##### `is_infill` [#is_infill]
* Type:Boolean
* Required:No
* Description:Whether it is fill mode
#### Task Query [#task-query]
##### `ids` [#ids]
* Type:String\[]
* Required:Yes
* Description:List of task IDs to be queried
##### `action` [#action]
* Type:String
* Required:No
* Description:Task type, optional values: MUSIC, LYRICS
## 📥 Response [#-response]
All interfaces return a unified JSON format response:
```json
{
"code":"success",
"message":"",
"data":"{{RESULT}}"
}
```
### Successful Response [#successful-response]
#### Basic Response Fields [#basic-response-fields]
##### `code` [#code]
* Type:String
* Description:Request status, success means success
##### `message` [#message]
* Type:String
* Description:Error message when request fails
##### `data` [#data]
* Type:Different for different interfaces
* Description:Return data when request is successful
* Generate song, lyrics, upload audio, song concatenation interfaces: return task ID string
* Task query interfaces: return task object or task object array
#### Task Related Objects [#task-related-objects]
##### Task Object [#task-object]
###### `task_id` [#task_id-1]
* Type:String
* Description:Task ID
###### `notify_hook` [#notify_hook-2]
* Type:String
* Description:Callback address after task completion
###### `action` [#action-1]
* Type:String
* Description:Task type, optional values: MUSIC, LYRICS
###### `status` [#status]
* Type:String
* Description:Task status, optional values: IN\_PROGRESS, SUCCESS, FAIL
###### `fail_reason` [#fail_reason]
* Type:String
* Description:Task failure reason
###### `submit_time` [#submit_time]
* Type:Integer
* Description:Task submission timestamp
###### `start_time` [#start_time]
* Type:Integer
* Description:Task start timestamp
###### `finish_time` [#finish_time]
* Type:Integer
* Description:Task end timestamp
###### `progress` [#progress]
* Type:String
* Description:Task progress percentage
###### `data` [#data-1]
* Type:Different for different task types
* Description:
* Music generation task: song object array
* Lyrics generation task: lyrics object
##### Song Object [#song-object]
###### `id` [#id]
* Type:String
* Description:Song ID
###### `title` [#title-1]
* Type:String
* Description:Song title
###### `status` [#status-1]
* Type:String
* Description:Song status
###### `metadata` [#metadata]
* Type:Object
* Description:Song metadata
* tags:Song style tags
* prompt:Lyric used to generate song
* duration:Song duration
* error\_type:Error type
* error\_message:Error message
* audio\_prompt\_id:Audio prompt ID
* gpt\_description\_prompt:Description of inspiration source
###### `audio_url` [#audio_url]
* Type:String
* Description:URL address of song audio
###### `image_url` [#image_url]
* Type:String
* Description:URL address of song cover image
###### `video_url` [#video_url]
* Type:String
* Description:URL address of song video
###### `model_name` [#model_name]
* Type:String
* Description:Model name used to generate song
###### `major_model_version` [#major_model_version]
* Type:String
* Description:Major model version
##### Lyrics Object [#lyrics-object]
###### `id` [#id-1]
* Type:String
* Description:Lyrics ID
###### `text` [#text]
* Type:String
* Description:Lyrics content
###### `title` [#title-2]
* Type:String
* Description:Lyrics title
###### `status` [#status-2]
* Type:String
* Description:Lyrics status
## 🌟 Best Practices [#-best-practices]
1. Provide as detailed and specific song or lyric generation prompts as possible, avoiding overly general or abstract prompts
2. When querying task status, polling intervals are recommended to be 2-5 seconds to avoid excessive polling
3. Inspiration mode only needs to provide the gpt\_description\_prompt parameter, the API will automatically generate lyrics, titles, tags, etc.
4. Custom mode requires prompt, title, tags parameters, which can have more control over the song
5. Try to use the latest model (such as chirp-v4), the effect will be better
6. Using the callback notification function (notify\_hook parameter) can reduce polling frequency and improve efficiency
7. Music continuation and concatenation functions can generate more rich and complete works on the original music
8. Pay attention to possible exceptions and errors, such as network timeouts, parameter validation failures, etc.
# Token Usage Query (/en/api/token-usage)
Retrieve the current Bearer token's quota usage: total granted, used, available, unlimited flag, model limits and expiration time.
## 📮 Endpoint [#-endpoint]
```
GET /api/usage/token
```
* Requires Authorization header
* Returns usage info for the token used in the current request
## 🔐 Authentication [#-authentication]
Include the following header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
* `sk-` prefix is accepted but optional; the server normalizes it
* Missing or invalid Authorization header returns 401
## 💡 Request Example [#-request-example]
```bash
curl -X GET https://api.zipflow.xyz/api/usage/token \
-H "Authorization: Bearer $ZIPFLOW_API_KEY"
```
## ✅ Success Response Example [#-success-response-example]
```json
{
"code": true,
"message": "ok",
"data": {
"object": "token_usage",
"name": "Default Token",
"total_granted": 1000000,
"total_used": 12345,
"total_available": 987655,
"unlimited_quota": false,
"model_limits": {
"gpt-4o-mini": true
},
"model_limits_enabled": false,
"expires_at": 0
}
}
```
## ❗ Error Response Examples [#-error-response-examples]
* Missing Authorization header:
```json
{
"success": false,
"message": "No Authorization header"
}
```
* Invalid scheme (non-Bearer):
```json
{
"success": false,
"message": "Invalid Bearer token"
}
```
* Token fetch failed (e.g., invalid or deleted):
```json
{
"success": false,
"message": "token not found"
}
```
## 🧾 Field Descriptions (data) [#-field-descriptions-data]
* `object`: Always `token_usage`
* `name`: Token name
* `total_granted`: Total granted (= used + available)
* `total_used`: Used quota
* `total_available`: Remaining available quota
* `unlimited_quota`: Whether the token has unlimited quota
* `model_limits`: Allowed model list
* `model_limits_enabled`: Whether model-specific limits are enabled
* `expires_at`: Expiration Unix timestamp in seconds. `0` means never expires (backend normalizes `-1` → `0`).
***
> Reference: `GET /api/usage/token` added in PR [#1161](https://github.com/QuantumNous/zipflow/pull/1161)
# List Models (Model) (/en/api/v1-models)
Lists the models your API key can access, in the standard OpenAI `GET /v1/models` format. Use a returned `id` as the `model` value in inference requests.
## 📮 Endpoint [#-endpoint]
```
GET /v1/models
```
* Requires Authorization header
* Returns the models available to the token used in the current request
## 🔐 Authentication [#-authentication]
Include the following header for API key authentication:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
* `sk-` prefix is accepted but optional; the server normalizes it
* Missing or invalid Authorization header returns 401
## 💡 Request Example [#-request-example]
```bash
curl https://api.zipflow.xyz/v1/models \
-H "Authorization: Bearer $ZIPFLOW_API_KEY"
```
## ✅ Success Response Example [#-success-response-example]
```json
{
"object": "list",
"data": [
{
"id": "gpt-4.1",
"object": "model",
"created": 1686935002,
"owned_by": "openai"
},
{
"id": "claude-sonnet-4",
"object": "model",
"created": 1686935002,
"owned_by": "anthropic"
}
]
}
```
## ❗ Error Response Examples [#-error-response-examples]
* Missing Authorization header:
```json
{
"error": {
"message": "You did not provide an API key. Provide your API key in an Authorization header using Bearer auth.",
"type": "invalid_request_error",
"param": null,
"code": null
}
}
```
* Invalid API key:
```json
{
"error": {
"message": "Incorrect API key provided.",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}
```
## 🧾 Field Descriptions [#-field-descriptions]
* `object`: Always `list`
* `data`: Array of available model entries
* `id`: Model identifier - pass this as `model` in inference requests
* `object`: Always `model`
* `created`: Creation Unix timestamp in seconds
* `owned_by`: Provider or organization that owns the model
# Video API Usage Examples and Best Practices (/en/api/video-examples)
This document provides complete usage examples and a best practices guide for the ZipFlow video generation API.
## Complete Usage Workflow Example [#complete-usage-workflow-example]
### 1. ZipFlow Format Complete Workflow [#1-zipflow-format-complete-workflow]
```javascript
// 1. Generate Video
async function generateVideoWithZipFlow() {
const response = await fetch('https://api.zipflow.xyz/v1/video/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'kling-v1',
prompt: '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级',
size: '1920x1080',
duration: 5,
metadata: {
seed: 20231234,
negative_prompt: '模糊, 低质量'
}
})
});
const result = await response.json();
return result.task_id;
}
// 2. Poll Status
async function pollVideoStatus(taskId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/video/generations/${taskId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`Video generation failed: ${result.error?.message || 'Unknown error'}`);
}
// Wait and retry
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('Maximum polling attempts reached');
}
// 3. Download Video
async function downloadVideo(taskId) {
const response = await fetch(`https://api.zipflow.xyz/v1/videos/${taskId}/content`, {
headers: {
'Authorization': 'Bearer sk-xxxx'
}
});
if (!response.ok) {
throw new Error(`Download failed: ${response.statusText}`);
}
const blob = await response.blob();
return blob;
}
// Complete workflow example
async function completeVideoWorkflow() {
try {
// Generating video...
console.log('正在生成视频...');
const taskId = await generateVideoWithZipFlow();
console.log('Task ID:', taskId);
// Querying generation status...
console.log('正在查询生成状态...');
const result = await pollVideoStatus(taskId);
console.log('Video generation complete:', result.url);
// Downloading video...
console.log('正在下载视频...');
const videoBlob = await downloadVideo(taskId);
// Save video
const url = URL.createObjectURL(videoBlob);
const a = document.createElement('a');
a.href = url;
a.download = `video_${taskId}.mp4`;
a.click();
URL.revokeObjectURL(url);
console.log('Video download complete');
} catch (error) {
console.error('Workflow failed:', error);
}
}
```
### 2. OpenAI Compatible Format Complete Workflow [#2-openai-compatible-format-complete-workflow]
```javascript
// 1. Generate Video (OpenAI Format)
async function generateVideoWithOpenAIFormat() {
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'sora-2',
prompt: '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级',
seconds: '5',
size: '1920x1080'
})
});
const result = await response.json();
return result.id;
}
// 2. Poll Status (OpenAI Format)
async function pollVideoStatusOpenAI(videoId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/videos/${videoId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`Video generation failed: ${result.error?.message || 'Unknown error'}`);
}
// Wait and retry
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('Maximum polling attempts reached');
}
```
## Detailed Examples for Different Models [#detailed-examples-for-different-models]
### Kling AI Example [#kling-ai-example]
```bash
# Text-to-Video
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v1",
"prompt": "一只橘猫在阳光下打盹，毛发蓬松，表情安详",
"duration": 5,
"metadata": {
"seed": 12345,
"negative_prompt": "模糊, 扭曲",
"cfg_scale": 0.8
}
}'
# Image-to-Video
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v2-master",
"image": "https://example.com/cat.jpg",
"prompt": "猫咪慢慢睁开眼睛，伸懒腰",
"duration": 3,
"metadata": {
"seed": 54321,
"negative_prompt": "快速动作",
"camera_control": {
"type": "simple",
"config": {
"horizontal": 1.0,
"vertical": 0,
"zoom": 0.5
}
}
}
}'
```
### Jimeng Example [#jimeng-example]
```bash
# Text-to-Video
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "海浪拍打着礁石，溅起白色的浪花",
"metadata": {
"req_key": "jimeng_vgfm_t2v_l20",
"aspect_ratio": "16:9",
"duration": 5
}
}'
# Image-to-Video
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng_vgfm_i2v_l20",
"image": "https://example.com/landscape.jpg",
"prompt": "云朵缓缓飘过天空",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": ["https://example.com/landscape.jpg"],
"aspect_ratio": "16:9"
}
}'
```
### Vidu Example [#vidu-example]
```bash
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq1",
"prompt": "未来城市的夜景，霓虹灯闪烁",
"size": "1920x1080",
"duration": 5,
"metadata": {
"resolution": "1080p",
"movement_amplitude": "medium",
"bgm": true,
"seed": 0,
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
## Error Handling Best Practices [#error-handling-best-practices]
### 1. Complete Error Handling Example [#1-complete-error-handling-example]
```javascript
class VideoAPIClient {
constructor(apiKey, baseUrl) {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
}
async generateVideo(params, format = 'zipflow') {
try {
const endpoint = format === 'openai' ? '/v1/videos' : '/v1/video/generations';
const response = await fetch(`${this.baseUrl}${endpoint}`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(params)
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
return await response.json();
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
throw new VideoAPIError(0, { message: error.message });
}
}
async pollStatus(taskId, format = 'zipflow', options = {}) {
const {
maxAttempts = 30,
initialDelay = 2000,
maxDelay = 30000
} = options;
let delay = initialDelay;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const endpoint = format === 'openai'
? `/v1/videos/${taskId}`
: `/v1/video/generations/${taskId}`;
const response = await fetch(`${this.baseUrl}${endpoint}`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new VideoAPIError(400, {
message: result.error?.message || 'Video generation failed'
});
}
// Wait and retry
await this.sleep(delay);
delay = Math.min(delay * 1.5, maxDelay);
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
console.error(`Attempt ${attempt + 1} polling failed:`, error);
if (attempt === maxAttempts - 1) {
throw new VideoAPIError(0, { message: 'Polling timeout' });
}
}
}
}
async downloadVideo(taskId) {
try {
const response = await fetch(`${this.baseUrl}/v1/videos/${taskId}/content`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`
}
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
return await response.blob();
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
throw new VideoAPIError(0, { message: error.message });
}
}
sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
class VideoAPIError extends Error {
constructor(status, data) {
super(data.message || 'Unknown error');
this.status = status;
this.data = data;
this.name = 'VideoAPIError';
}
}
// Usage example
async function exampleUsage() {
const client = new VideoAPIClient('sk-xxxx', 'https://api.zipflow.xyz');
try {
// Generate video
const result = await client.generateVideo({
model: 'kling-v1',
prompt: '一只可爱的小狗在花园里玩耍',
duration: 5
});
console.log('Task creation successful:', result.task_id);
// Poll status
const status = await client.pollStatus(result.task_id, 'zipflow', {
maxAttempts: 20,
initialDelay: 3000
});
console.log('Video generation complete:', status.url);
// Download video
const videoBlob = await client.downloadVideo(result.task_id);
console.log('Video size:', videoBlob.size);
} catch (error) {
if (error instanceof VideoAPIError) {
console.error(`API Error (${error.status}):`, error.message);
} else {
console.error('Unknown error:', error);
}
}
}
```
## Performance Optimization Suggestions [#performance-optimization-suggestions]
### 1. Concurrency Control [#1-concurrency-control]
```javascript
class VideoGenerationManager {
constructor(client, maxConcurrent = 3) {
this.client = client;
this.maxConcurrent = maxConcurrent;
this.running = 0;
this.queue = [];
}
async generateVideo(params) {
return new Promise((resolve, reject) => {
this.queue.push({ params, resolve, reject });
this.processQueue();
});
}
async processQueue() {
if (this.running >= this.maxConcurrent || this.queue.length === 0) {
return;
}
this.running++;
const { params, resolve, reject } = this.queue.shift();
try {
const result = await this.client.generateVideo(params);
const status = await this.client.pollStatus(result.task_id);
resolve(status);
} catch (error) {
reject(error);
} finally {
this.running--;
this.processQueue();
}
}
}
```
### 2. Caching Strategy [#2-caching-strategy]
```javascript
class VideoCache {
constructor(ttl = 3600000) { // 1 hour
this.cache = new Map();
this.ttl = ttl;
}
generateKey(params) {
return JSON.stringify(params);
}
get(params) {
const key = this.generateKey(params);
const cached = this.cache.get(key);
if (cached && Date.now() - cached.timestamp < this.ttl) {
return cached.result;
}
this.cache.delete(key);
return null;
}
set(params, result) {
const key = this.generateKey(params);
this.cache.set(key, {
result,
timestamp: Date.now()
});
}
clear() {
this.cache.clear();
}
}
```
## Monitoring and Logging [#monitoring-and-logging]
### 1. Performance Monitoring [#1-performance-monitoring]
```javascript
class VideoAPIMonitor {
constructor() {
this.metrics = {
totalRequests: 0,
successfulRequests: 0,
failedRequests: 0,
averageResponseTime: 0,
errorTypes: new Map()
};
}
async measureTime(fn) {
const start = Date.now();
try {
const result = await fn();
this.recordSuccess(Date.now() - start);
return result;
} catch (error) {
this.recordFailure(Date.now() - start, error);
throw error;
}
}
recordSuccess(responseTime) {
this.metrics.totalRequests++;
this.metrics.successfulRequests++;
this.updateAverageResponseTime(responseTime);
}
recordFailure(responseTime, error) {
this.metrics.totalRequests++;
this.metrics.failedRequests++;
this.updateAverageResponseTime(responseTime);
const errorType = error.constructor.name;
this.metrics.errorTypes.set(
errorType,
(this.metrics.errorTypes.get(errorType) || 0) + 1
);
}
updateAverageResponseTime(responseTime) {
const total = this.metrics.totalRequests;
this.metrics.averageResponseTime =
(this.metrics.averageResponseTime * (total - 1) + responseTime) / total;
}
getMetrics() {
return {
...this.metrics,
successRate: this.metrics.totalRequests > 0
? this.metrics.successfulRequests / this.metrics.totalRequests
: 0
};
}
}
```
## Best Practices Summary [#best-practices-summary]
### 1. API Selection [#1-api-selection]
* **ZipFlow Format** (`/v1/video/generations`): Suitable for scenarios requiring more custom parameters
* **OpenAI Format** (`/v1/videos`): Suitable for scenarios integrating with the OpenAI ecosystem
### 2. Error Handling [#2-error-handling]
* Implement exponential backoff retry mechanism
* Distinguish between transient and permanent errors
* Provide meaningful error messages
### 3. Performance Optimization [#3-performance-optimization]
* Control the number of concurrent requests
* Implement an appropriate caching strategy
* Monitor API call performance
### 4. User Experience [#4-user-experience]
* Provide progress feedback
* Implement timeout handling
* Support cancellation operations
### 5. Resource Management [#5-resource-management]
* Download generated videos promptly
* Clean up temporary files
* Monitor storage usage
These best practices can help you build stable and efficient video generation applications.
# Xinference Rerank Format (/en/api/xinference-rerank)
In ZipFlow, Xinference's rerank response structure will be formatted as Jina's rerank response structure, with the same usage as Jina's rerank. **For Dify and other client users**: When configuring, please select **Jina AI** as the provider type, not Xinference, and use the model names supported by Xinference.
## 📝 Introduction [#-introduction]
Xinference's rerank API is fully compatible with Jina AI's rerank API. Please refer to the [Jina AI Rerank Format](/en/api/jinaai-rerank) documentation for detailed usage methods, request parameters, and response formats.
## 💡 Usage [#-usage]
When using Xinference rerank API, simply set the `model` parameter to a rerank model supported by Xinference. All other parameters and usage methods are the same as Jina AI's rerank API.
### Example Request [#example-request]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jina-reranker-v2",
"query": "What is the capital of the United States?",
"documents": [
"The capital of Nevada is Carson City.",
"The Northern Mariana Islands are a group of islands in the Pacific Ocean, with Saipan as their capital.",
"Washington, D.C. (also known as Washington or D.C., officially the District of Columbia) is the capital of the United States.",
"Capitalization in English grammar is the use of capital letters at the beginning of words. English usage differs from capitalization in other languages.",
"The death penalty has existed in the United States since before it became a country. As of 2017, the death penalty is legal in 30 of the 50 states."
],
"top_n": 3
}'
```
For more detailed information, please refer to the [Jina AI Rerank Format](/en/api/jinaai-rerank) documentation.
# ZipFlow 文档 (/zh)
欢迎来到 ZipFlow 文档。ZipFlow 是一个模型 API 服务：一个账号、一个
Base URL（`https://api.zipflow.xyz/v1`）即可兼容多种接口格式 ——
OpenAI、Anthropic、Google Gemini、DeepSeek 等，覆盖对话、嵌入、重排序、
图像、音频、音乐与视频。
在 [ZipFlow 控制台](https://zipflow.xyz) 获取 API 密钥，然后开始调用：
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{"model": "gpt-4.1", "messages": [{"role": "user", "content": "你好！"}]}'
```
## 浏览文档 [#浏览文档]
* [对话补全](/zh/api/openai-chat)
* [Anthropic 对话格式](/zh/api/anthropic-chat)
* [Google Gemini](/zh/api/google-gemini-chat)
* [图像生成](/zh/api/openai-image)
* [视频生成](/zh/api/openai-video)
* [实时对话](/zh/api/openai-realtime)
* [模型列表](/zh/api/v1-models)
* [应用接入](/zh/apps/cherry-studio)
# 隐私政策 (/zh/privacy)
**最后更新：2026 年 8 月 17 日**
ZipFlow（下称“我们”）提供模型 API 服务，让您通过单一接口访问多种 AI 模型（下称“服务”），以及位于 [https://zipflow.xyz](https://zipflow.xyz) 的网站及其相关文档（下称“网站”）。本隐私政策说明了当您使用网站和服务时，我们如何收集、使用、共享和保护与您相关的信息。
使用网站或服务即表示您同意本隐私政策所述的做法。如您不同意，请勿使用网站或服务。
## 1. 我们收集的信息 [#1-我们收集的信息]
### 您主动提供给我们的信息 [#您主动提供给我们的信息]
* **账户信息**：注册时，我们会收集您的用户名、电子邮箱和密码等信息（密码以哈希形式存储）。
* **沟通记录**：当您联系我们（例如寻求支持）时，我们会收集您的消息内容及联系方式。
* **账单与支付信息**：当您充值或购买时，我们会处理交易详情，例如金额、支付方式和账单记录。支付处理可能由第三方支付服务商完成。
### 我们自动收集的信息 [#我们自动收集的信息]
当您访问网站或使用服务时，我们可能会自动收集：
* **使用与日志数据**：IP 地址、浏览器类型与版本、操作系统、来源页面、访问页面及时间戳。
* **服务数据**：API 请求元数据，例如所用模型、请求与响应的令牌数量、延迟、时间戳和费用，用于计费、用量分析和防止滥用。
* **Cookie 及类似技术**：我们使用 Cookie 及类似技术来保持您的登录状态、记住您的偏好并了解网站的使用情况。详见下文的“Cookie 与追踪技术”。
### 您通过服务提交的内容 [#您通过服务提交的内容]
当您使用 API 时，您将内容（下称“输入”）提交给 ZipFlow，由 ZipFlow 的模型生成回复（下称“输出”）。
**我们对您内容的承诺：** ZipFlow 不会阅读、监控或出售您的输入或输出，也不会使用它们来训练模型。我们处理您的内容，仅用于交付服务——即生成回复、计量用量以及防止滥用或欺诈——或履行法律要求。
## 2. 我们如何使用您的信息 [#2-我们如何使用您的信息]
我们将所收集的信息用于：
* 提供、运营和维护服务；
* 生成对您请求的回复；
* 处理交易并管理您的账户与余额；
* 计量并报告用量、令牌和费用；
* 检测、预防并处理欺诈、滥用、安全事件和技术问题；
* 就您的账户、服务更新和支持请求与您沟通；
* 履行法律义务并执行我们的条款；以及
* 改进和发展网站与服务。
## 3. 我们如何共享您的信息 [#3-我们如何共享您的信息]
我们不会出售您的个人信息。在下列情形下，我们可能会共享信息：
* **服务提供商**：与代表我们提供服务（如托管、支付处理和数据分析）的供应商共享，并受保密义务约束。
* **法律与安全**：在法律、法规、法律程序或政府要求所必需，或为保护 ZipFlow、我们的用户或公众的权利、财产或安全所必需时。
* **业务转移**：在与合并、收购、重组或资产出售相关的情况下。
* **经您同意**：用于您授权的任何其他目的。
我们还可能共享无法合理用于识别您身份的汇总或去标识化信息。
## 4. 数据留存 [#4-数据留存]
我们仅在提供服务、履行法律与监管义务、解决争议和执行协议所必需的期限内保留个人信息。
* **请求日志（元数据）**：所用模型、令牌数量、延迟、费用和时间戳等详情，最长保留 30 天，用于计费、用量分析和防止滥用。
* **内容（输入与输出）**：我们不会将您的提示词或回复内容持久化到超过交付回复所必需的时间，也不会为自身目的保留这些内容。
当信息不再需要时，我们将依据适用法律予以删除或匿名化。
## 5. 数据安全 [#5-数据安全]
我们采用合理的技术和组织措施，旨在保护您的信息免遭未经授权的访问、丢失、滥用或篡改。然而，任何通过互联网传输或电子存储的方式都不是绝对安全的，我们无法保证绝对安全。您有责任保管好您的账户凭据和 API 密钥。
## 6. Cookie 与追踪技术 [#6-cookie-与追踪技术]
我们使用 Cookie 及类似技术来记住您的偏好、保持您的登录状态并分析网站的使用情况。您可以通过浏览器设置控制 Cookie；禁用 Cookie 可能会影响网站的某些功能。
## 7. 第三方服务与链接 [#7-第三方服务与链接]
网站和服务可能包含指向第三方网站和服务的链接，或依赖第三方网站和服务（包括支付处理商）。我们对这些第三方的隐私做法不承担责任。本隐私政策仅适用于 ZipFlow 收集的信息。我们建议您查阅所交互的任何第三方服务的隐私政策。
## 8. 国际数据传输 [#8-国际数据传输]
ZipFlow 在全球范围内运营，您的信息可能会被传输到您所在国家以外的国家并在那里处理。在适用法律要求的情况下，我们会为此类传输采取适当的保障措施。
## 9. 您的权利与选择 [#9-您的权利与选择]
根据您所在地区，您可能对个人信息享有相关权利，例如访问、更正、删除或限制处理您的信息的权利，以及反对某些处理的权利。如需行使这些权利，请通过下方地址联系我们。您也可以登录控制台更新账户信息，并可通过营销信息中的退订指引选择退出营销通讯。
## 10. 儿童隐私 [#10-儿童隐私]
网站和服务不面向 13 岁以下的儿童，我们不会在知情的情况下收集 13 岁以下儿童的个人信息。如果您认为某名儿童向我们提供了个人信息，请联系我们以便删除。
## 11. 本隐私政策的变更 [#11-本隐私政策的变更]
我们可能会不时更新本隐私政策。更新时，我们会修改本页顶部的“最后更新”日期。我们建议您定期查看本页。在变更发布后继续使用网站或服务，即表示您接受修订后的政策。
## 12. 联系我们 [#12-联系我们]
如您对本隐私政策或我们的隐私做法有任何疑问或顾虑，请通过 [support@zipflow.xyz](mailto:support@zipflow.xyz) 联系我们。
# Cherry Studio - 桌面 AI 客户端 (/zh/apps/cherry-studio)
在 ZipFlow 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 Cherry Studio：
```json
{ "Cherry Studio": "cherrystudio://providers/api-keys?v=1&data={cherryConfig}" }
```
🍒 Cherry Studio 是一款功能强大的桌面 AI 客户端，专为专业用户设计，集成了 30+ 行业智能助手，能够满足各种工作场景的需求，显著提升工作效率。
* 官网地址：[https://cherry-ai.com/](https://cherry-ai.com/)
* 下载地址：[https://cherry-ai.com/download](https://cherry-ai.com/download)
* 官方文档：[https://docs.cherry-ai.com](https://docs.cherry-ai.com)
## ZipFlow 接入方法 [#zipflow-接入方法]
### 参数填写 [#参数填写]
提供商类型：ZipFlow 支持的类型\
API 密钥：于 ZipFlow 获取\
API 地址：ZipFlow 站点地址
### 图文指引 [#图文指引]
1. 在 ZipFlow 中复制 API key
2. 添加提供商
3. 添加模型
4. 返回聊天页面
5. 切换 ZipFlow 模型
## 在 Cherry Studio 中画图 [#在-cherry-studio-中画图]
1. 首先添加支持画图的模型
2. 画图
# Claude Code (/zh/apps/claude-code)
***
Unleash Claude’s raw power directly in your terminal. Search million-line codebases instantly. Turn hours-long workflows into a single command. Your tools. Your workflow. Your codebase, evolving at thought speed.
直接在你的终端中，释放 Claude 的强大威力。瞬间搜索百万行代码库。将数小时的工作流化为一条命令。你的工具。你的工作流。你的代码库，以思维速度进化。
1. 官方主页：[https://www.anthropic.com/claude-code](https://www.anthropic.com/claude-code)
2. 安装方法：见本页下方教程
## 效果演示 [#效果演示]
***
### 特性 [#特性]
| **功能分类** | **特性** |
| ----------- | ------------------------------------ |
| **代码理解** | - 深度代码库分析，利用智能代理搜索理解项目结构和依赖 |
| | - 自动生成高层次代码概述，快速帮助用户理解代码库 |
| **代码编辑** | - 支持多文件协同编辑，适用于复杂代码修改 |
| | - 提供符合项目模式和架构的实际可用代码建议 |
| **集成能力** | - 支持在终端中直接运行，无需切换上下文 |
| | - 与VS Code和JetBrains IDE无缝集成，无需复制粘贴 |
| **代码生成和优化** | - 自动生成代码、创建测试、修复错误，支持从概念到提交的完整流程 |
| | - 为代码生成和理解优化，结合Claude Opus 4等先进模型 |
| **安全与灵活性** | - 改动需获得用户明确授权，文件和命令操作更安全 |
| | - 适应用户代码规范，支持自定义配置 |
| **工具链整合** | - 支持与GitHub、GitLab等工具结合，实现自动化工作流程 |
| | - 与测试套件、构建系统集成，增强现有开发工具 |
| **跨平台与扩展** | - 支持Windows、macOS、Linux操作系统 |
| | - 可配置运行在SDK或GitHub Actions中，灵活适配不同需求 |
| **主要应用场景** | - 代码库入门和理解、新成员快速上手 |
| | - 代码问题修复与优化流程，从分析问题到提交PR |
| | - 项目代码重构与新功能实现 |
| **用户反馈亮点** | - 提升日常开发效率，省去例行任务消耗的时间 |
| | - 处理复杂多步骤任务表现优异，扩展开发可能性 |
## AI 模型配置方法 [#ai-模型配置方法]
### Windows 端图文指引 [#windows-端图文指引]
#### 1.安装 Node.js 环境 [#1安装-nodejs-环境]
Claude Code 需要 Node.js 环境才能运行。
* 打开浏览器访问 [https://nodejs.org/](https://nodejs.org/)
* 点击 "LTS" 版本进行下载（推荐长期支持版本）
* 下载完成后双击 .msi 文件
* 按照安装向导完成安装，保持默认设置即可
* 建议使用 PowerShell 而不是 CMD
* 如果遇到权限问题，尝试以管理员身份运行
* 某些杀毒软件可能会误报，需要添加白名单
安装完成后，打开 PowerShell 或 CMD，输入以下命令：
```
node --version
npm --version
```
如果显示版本号，说明安装成功
#### 2.安装 Git Bash [#2安装-git-bash]
Windows 环境下需要使用 Git Bash 安装 Claude code。安装完成后，环境变量设置和使用 Claude Code 仍然在普通的 PowerShell 或 CMD 中进行。
* 访问 [https://git-scm.com/downloads/win](https://git-scm.com/downloads/win)
* 点击 "Download for Windows" 下载安装包
* 运行下载的 .exe 安装文件
* 在安装过程中保持默认设置，直接点击 "Next" 完成安装
安装完成后，打开 Git Bash，输入以下命令验证：
```
git --version
```
如果显示版本号，说明安装成功
#### 3.安装 Claude Code [#3安装-claude-code]
打开 PowerShell，运行以下命令：
```
npm install -g @anthropic-ai/claude-code
```
这个命令会从 npm 官方仓库下载并安装最新版本的 Claude Code。
```
[Environment]::SetEnvironmentVariable('Path', ([Environment]::GetEnvironmentVariable('Path','User') + ";$HOME\.local\bin"), 'User')
```
安装完成后，输入以下命令检查是否安装成功：
```
claude --version
```
如果显示版本号，恭喜你！Claude Code 已经成功安装了。
#### 4.设置环境变量 [#4设置环境变量]
为了让 Claude Code 连接到你的服务，需要设置多个环境变量：
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.ps1')
```
#### 5.开始使用 Claude Code [#5开始使用-claude-code]
现在你可以开始使用 Claude Code 了！
打开 PowerShell，直接启动 Claude Code:
```
# 启动 Claude Code
claude
```
在特定项目中使用:
```
# 进入你的项目目录
cd C:\path\to\your\project
```
```
# 启动 Claude Code
claude
```
输入命令：
```
/model
```
Enter进入，选择模型，通常使用默认设置即可。
> 注意：设置环境变量修改后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
### MacOS 端图文指引 [#macos-端图文指引]
#### 1.安装 Claude Code CLI [#1安装-claude-code-cli]
打开终端
打开终端，运行以下命令：
```
curl -fsSL https://claude.ai/install.sh | bash
```
可选项：出现提示后运行提供的命令
```
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
```
#### 2.设置环境变量 [#2设置环境变量]
为了让 Claude Code 连接到第三方服务，需要设置环境变量：
输入命令：
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.sh | bash
```
安装完成后，输入以下命令检查是否安装成功：
```
claude --version
```
如果显示版本号，恭喜你！Claude Code 已经成功安装了。
#### 3.开始使用 Claude Code [#3开始使用-claude-code]
现在你可以开始使用 Claude Code 了！
直接启动 Claude Code:
```
# 启动 Claude Code
claude
```
在特定项目中使用:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Claude Code
claude
```
输入命令：
```
/model
```
Enter进入，选择官方模型选择，通常使用默认模型即可
> 注意：设置环境变量修改`ANTHROPIC_BASE_URL`后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
#### 6.macOS 常见问题解决 [#6macos-常见问题解决]
??? example "macOS 安全设置阻止运行"
如果系统阻止运行 Claude Code：
* 打开"系统偏好设置" → "安全性与隐私"
* 点击"仍要打开"或"允许"
* 或者在`Terminal`中运行：`sudo spctl --master-disable`
### Linux 端图文指引 [#linux-端图文指引]
#### 1.安装 Claude Code [#1安装-claude-code]
打开终端，运行以下命令：
```
curl -fsSL https://claude.ai/install.sh | bash
```
如果遇到权限问题，可以使用 sudo：
```
sudo curl -fsSL https://claude.ai/install.sh | bash
```
安装完成后，输入以下命令检查是否安装成功：
```
claude --version
```
如果显示版本号，恭喜你！Claude Code 已经成功安装了。
#### 2.设置环境变量 [#2设置环境变量-1]
为了让 Claude Code 连接到你的服务，需要设置两个环境变量：
输入命令：
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/claude-cli-setup.sh | bash
```
#### 4.开始使用 Claude Code [#4开始使用-claude-code]
现在你可以开始使用 Claude Code 了！
直接启动 Claude Code:
```
# 启动 Claude Code
claude
```
在特定项目中使用:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Claude Code
claude
```
输入命令：
```
/model
```
Enter进入，选择官方模型选择，通常使用默认模型即可
> 注意：设置环境变量修改`ANTHROPIC_BASE_URL`后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
#### 5.Linux 常见问题解决 [#5linux-常见问题解决]
??? example "缺少依赖库"
某些 Linux 发行版需要安装额外依赖：
```
# Ubuntu/Debian
sudo apt install build-essential
```
```
# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```
??? example "环境变量不生效"
检查以下几点：
* 确认修改了正确的配置文件（`.bashrc`或`.zshrc`）
* 重新启动终端或运行`source ~/.bashrc`
* 验证设置：`echo $ANTHROPIC_BASE_URL`
# OpenAI Codex CLI (/zh/apps/codex-cli)
***
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
Codex CLI 是一个来自 OpenAI 的编码代理，可在您的计算机上本地运行。
1. 官方主页：[https://chatgpt.com/codex](https://chatgpt.com/codex)
2. 项目主页：[https://github.com/openai/codex](https://github.com/openai/codex)
3. 安装方法：见本页下方教程
## 效果演示 [#效果演示]
***
### 特性 [#特性]
| **功能分类** | **特性** |
| -------- | -------------------------------------------------------------------------------------------- |
| 终端式编码助手 | Codex CLI 是一个基于终端的交互式编码助理，用于在命令行中编辑代码、生成补丁并运行命令。 |
| 工具驱动架构 | 提供 `apply_patch`、`shell`、`update_plan`、`multi_tool_use` 等工具，用于对仓库文件和操作进行可控修改。 |
| 原子补丁编辑 | 使用专门的补丁格式通过 `apply_patch` 原子地添加/更新/删除文件，便于审计与回滚。 |
| 沙箱与审批 | 支持沙箱策略（如 `workspace-write`、`read-only`）和审批模式（`on-request`、`on-failure`、`never`），控制写入与网络访问权限。 |
| 计划追踪 | `update_plan` 用于列出步骤并跟踪状态，要求始终只有一个 `in_progress` 步骤以保持明确进度。 |
| 交互规范 | 在重要操作前发送简短前导说明，保持语气友好、简洁并提供进度更新。 |
| 安全约束 | 遵循严格规则（不随意更改无关文件、不添加版权头、不执行破坏性命令），需要用户批准敏感操作。 |
| 测试与格式化 | 推荐在修改后运行相关测试与格式化工具，但不负责修复与当前任务无关的问题。 |
| 输出与风格 | 最终输出遵循 CLI 渲染规范（例如 `**` 标题、反引号表示路径/命令），保持可扫描的简洁结构。 |
| 并行执行 | 支持通过 `multi_tool_use.parallel` 并行运行多个工具以提升效率。 |
## AI 模型配置方法 [#ai-模型配置方法]
### Windows 端图文指引 [#windows-端图文指引]
#### 1.打开终端 [#1打开终端]
#### 2.安装 WSL [#2安装-wsl]
为在 Windows 上获得最佳性能，请安装并使用 Windows Subsystem for Linux (WSL2)。
```
wsl --install
```
安装完成后重启 Windows 计算机
* 建议使用 PowerShell 而不是 CMD
* 如果遇到权限问题，尝试以管理员身份运行
* 某些杀毒软件可能会误报，需要添加白名单
```
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
```
标签栏新开一个 PowerShell 窗口，打开 WSL
```
wsl
```
安装 Node.js
版本号有时效性，请根据 OpenAI 官网要求安装对应版本：[https://developers.openai.com/codex/windows](https://developers.openai.com/codex/windows)
```
nvm install 22
```
#### 3.安装 Codex CLI [#3安装-codex-cli]
```
npm i -g @openai/codex
```
这个命令会从 npm 官方仓库下载并安装最新版本的 Codex CLI。
#### 4.修改配置文件 [#4修改配置文件]
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.ps1')
```
#### 5.开始使用 Codex CLI [#5开始使用-codex-cli]
现在你可以开始使用 Codex CLI 了！
启动 WSL2
```
wsl
```
直接启动 Codex CLI:
```
codex
```
在特定项目中使用:
```
cd mnt/c/path/to/your/project
```
```
codex
```
Enter 启动 Codex CLI
> 设置 Codex CLI 的权限：1.允许 Codex 直接修改文件；2.Codex 修改文件需要手动授权
```
/model
```
> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
### macOS 端图文指引 [#macos-端图文指引]
#### 1.安装 Homebrew (已安装请跳过) [#1安装-homebrew-已安装请跳过]
Homebrew 是 macOS 缺失的软件包的管理器。
官网：[https://brew.sh](https://brew.sh)
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
#### 2.安装 Node.js 环境 [#2安装-nodejs-环境]
更新 Homebrew
```
brew update
```
安装 Node.js
```
brew install node
```
* 如果遇到权限问题，可能需要使用`sudo`
* 首次运行可能需要在系统偏好设置中允许
* 建议使用`Terminal`或`iTerm2`
安装完成后，打开终端，输入以下命令：
```
node --version
npm --version
```
如果显示版本号，说明安装成功
#### 3.安装 Codex CLI [#3安装-codex-cli-1]
打开终端，运行以下命令：
```
# 全局安装 Codex CLI
npm install -g @openai/codex
```
如果遇到权限问题，可以使用 sudo：
```
sudo npm install -g @openai/codex
```
安装完成后，输入以下命令检查是否安装成功：
```
codex --version
```
如果显示版本号，恭喜你！Codex CLI 已经成功安装了。
#### 4.修改配置文件 [#4修改配置文件-1]
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```
#### 5.开始使用 Codex CLI [#5开始使用-codex-cli-1]
现在你可以开始使用 Codex CLI 了！
直接启动 Codex CLI:
```
codex
```
在特定项目中使用:
```
cd mnt/c/path/to/your/project
```
```
codex
```
Enter 启动 Codex CLI
> 设置 Codex CLI 的权限：1.允许 Codex 直接修改文件；2.Codex 修改文件需要手动授权
> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
#### 6.macOS 常见问题解决 [#6macos-常见问题解决]
??? example "安装时提示权限错误"
尝试以下解决方法：
* 使用`sudo`安装：`sudo npm install -g @openai/codex`
* 或者配置`npm`使用用户目录：`npm config set prefix ~/.npm-global`
??? example "macOS 安全设置阻止运行"
如果系统阻止运行 Codex CLI：
* 打开"系统偏好设置" → "安全性与隐私"
* 点击"仍要打开"或"允许"
* 或者在`Terminal`中运行：`sudo spctl --master-disable`
### Linux 端图文指引 [#linux-端图文指引]
#### 1.安装 Node.js 环境 [#1安装-nodejs-环境]
Codex CLI 需要 Node.js 环境才能运行。
添加 NodeSource 仓库
```
sudo curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
```
安装 Node.js
```
sudo apt-get install -y nodejs
```
* 某些发行版可能需要安装额外的依赖
* 如果遇到权限问题，使用 sudo
* 确保你的用户在 npm 的全局目录有写权限
安装完成后，打开终端，输入以下命令：
```
node --version
npm --version
```
如果显示版本号，说明安装成功
#### 2.安装 Codex CLI [#2安装-codex-cli]
打开终端，运行以下命令：
```
# 全局安装 Codex CLI
npm install -g @openai/codex
```
如果遇到权限问题，可以使用 sudo：
```
sudo npm install -g @openai/codex
```
安装完成后，输入以下命令检查是否安装成功：
```
codex --version
```
如果显示版本号，恭喜你！Codex CLI 已经成功安装了。
#### 3.修改配置文件 [#3修改配置文件]
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/codex-cli-setup.sh | bash
```
#### 4.开始使用 Codex CLI [#4开始使用-codex-cli]
现在你可以开始使用 Codex CLI 了！
直接启动 Codex CLI:
```
# 启动 Codex CLI
codex
```
在特定项目中使用:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Codex CLI
codex
```
Enter 启动 Codex CLI
> 设置 Codex CLI 的权限：1.允许 Codex 直接修改文件；2.Codex 修改文件需要手动授权
> 注意：修改接口地址后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。
#### 5.Linux 常见问题解决 [#5linux-常见问题解决]
??? example "安装时提示权限错误"
尝试以下解决方法：
* 使用`sudo`安装：`sudo npm install -g @openai/codex`
* 或者配置`npm`使用用户目录：`npm config set prefix ~/.npm-global`
* 然后添加到`PATH`：`export PATH=~/.npm-global/bin:$PATH`
??? example "缺少依赖库"
某些 Linux 发行版需要安装额外依赖：
```
# Ubuntu/Debian
sudo apt install build-essential
```
```
# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
```
# Factory Droid CLI (/zh/apps/factory-droid-cli)
***
Command Line: Automation Across the SDLC. Script and parallelize Droids at massive scale for CI/CD, migrations, and maintenance. From automated code review to self-healing builds, integrate agents into every phase of development.
Droid CLI 是由 Factory AI 开发的命令行工具，旨在作为 AI 软件工程代理运行。它允许用户通过终端与各种大型语言模型交互，构建、调试和重构代码，甚至创建完整的应用程序。
1. 官方主页：[https://factory.ai/product/cli](https://factory.ai/product/cli)
2. 官方文档：[https://docs.factory.ai/cli/getting-started/quickstart](https://docs.factory.ai/cli/getting-started/quickstart)
3. 安装方法：见本页下方教程
## 效果演示 [#效果演示]
***
### 特性 [#特性]
| 类别 | 特性 | 价值/能力 | 示例/备注 | |
| --------- | ------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------- | ---------------- |
| 快速上手与 CLI | 30 秒安装；在项目目录中启动 droid 交互会话；支持 macOS/Linux 与 Windows | 快速接入当前工程，无需新工具 | Windows 安装：\`irm [https://app.factory.ai/cli/windows](https://app.factory.ai/cli/windows) | iex`；启动：`droid\` |
| 端到端特性开发 | 从规划到实现到测试的全流程自动化；透明的评审流程 | 提升交付速度，保持人类把控 | 原生 diff 查看与批准流程（见“透明与可控”） | |
| 代码库深度理解 | 融合组织在代码库、文档、Issue 追踪中的共享知识；上下文感知，效果随时间提升 | 更准确的建议与改动 | 持续利用跨仓库与文档的知识 | |
| 工程系统集成 | 原生集成 Jira、Notion、Slack 等工具；开发工作与团队流程保持同步 | 减少工具切换与信息孤岛 | “等”表示还有更多集成 | |
| 生产级自动化 | 工作流可在本地与 CI/CD 复用；企业级安全与合规内建 | 一致性与可审计性 | 适配流水线与企业环境 | |
| 企业级能力 | 私有部署选项、SOC-2 合规、空气隔离（air-gapped）环境 | 满足安全与合规要求 | 以安全与质量优先 | |
| 现有工具增强 | 在终端、IDE 与既有开发环境中工作；无需切换编辑器或学习新界面 | 保持现有工作习惯、低迁移成本 | 与熟悉工具深度集成 | |
| 透明与可控 | 每个决策可见且可审阅；对代码变更保持完全监督；原生 diff 查看与审批工作流 | 降低风险、提升可控性 | 审核友好、可追踪 | |
| 模型灵活性 | 不锁定单一 AI 提供商；按任务选择最佳模型；组织级一致行为与记忆 | 在性能与成本间做最优选择 | 支持多模型路由 | |
| 下一步与资源 | Quickstart、Common Use Cases、IDE Integration、Configuration、AGENTS.md | 便于落地与实践 | 见页面 “Next steps/Additional resources” | |
## AI 模型配置方法 [#ai-模型配置方法]
### Windows 端图文指引 [#windows-端图文指引]
#### 1.打开终端 [#1打开终端]
#### 2.安装 Factory Droid CLI [#2安装-factory-droid-cli]
官方一键安装命令：
```
irm https://app.factory.ai/cli/windows | iex
```
#### 3.修改配置文件 [#3修改配置文件]
Droid CLI 使用第三方 API 需要修改配置文件。
```
iex (irm 'https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/factory-cli-setup.ps1')
```
#### 4.开始使用 Droid CLI [#4开始使用-droid-cli]
现在你可以开始使用 Droid CLI 了！
直接启动 Droid CLI:
```
# 启动 Droid CLI
droid
```
在特定项目中使用:
```
# 进入你的项目目录
cd C:\path\to\your\project
```
```
# 启动 Droid CLI
droid
```
Enter 启动 Droid CLI
Droid CLI 要求用户登录官方账号（免费）后才能使用。
#### 5.Windows 常见问题解决 [#5windows-常见问题解决]
??? example "安装时提示 "permission denied" 错误"
这通常是权限问题，尝试以下解决方法：
* 以管理员身份运行`PowerShell`
* 或者配置`npm`使用用户目录：`npm config set prefix %APPDATA%\npm`
??? example "PowerShell 执行策略错误"
如果遇到执行策略限制，运行：
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### macOS/Linux 端图文指引 [#macoslinux-端图文指引]
#### 1.安装 Droid CLI [#1安装-droid-cli]
打开终端，运行以下命令：
```
curl -fsSL https://app.factory.ai/cli | sh
```
按照安装提示修改环境变量 (直接复制安装提示代码):
Linux 视情况选择 `~/.bashrc` 或 `~/.zshrc`
```
echo 'export PATH=/Users/修改此处/.local/bin:$PATH' >> ~/.zshrc
```
```
source ~/.zshrc
```
#### 2.修改配置文件 [#2修改配置文件]
Droid CLI 使用第三方 API 需要修改配置文件。
```
curl -fsSL https://raw.githubusercontent.com/QuantumNous/zipflow-docs/refs/heads/main/helper/factory-cli-setup.sh | bash
```
#### 3.开始使用 Droid CLI [#3开始使用-droid-cli]
现在你可以开始使用 Droid CLI 了！
直接启动 Droid CLI:
```
# 启动 Droid CLI
droid
```
在特定项目中使用:
```
# 进入你的项目目录
cd /path/to/your/project
```
```
# 启动 Droid CLI
droid
```
Enter 启动 Droid CLI
> Droid CLI 要求用户登录官方账号（免费）后才能使用。
# 流畅阅读 (FluentRead) - 开源翻译插件 (/zh/apps/fluent-read)
在 ZipFlow 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 FluentRead：
```json
{ "流畅阅读": "fluentread" }
```
🌊 流畅阅读（FluentRead）是一款开源浏览器翻译插件，致力于提供母语般的阅读体验。
* 项目地址：[https://github.com/Bistutu/FluentRead](https://github.com/Bistutu/FluentRead)
## 🌟 核心特性 [#-核心特性]
### 智能翻译引擎 [#智能翻译引擎]
* **多引擎支持**：支持 20+ 种翻译引擎
* **传统翻译**：微软翻译、谷歌翻译、DeepL翻译等
* **AI 大模型**：OpenAI、DeepSeek、Kimi、Ollama等
* **自定义引擎**：支持自定义翻译服务配置
### 沉浸式阅读体验 [#沉浸式阅读体验]
* **双语对照**：原文与译文并列显示，阅读更轻松
* **划词翻译**：选中任意文本，即时获得翻译结果
* **一键复制**：快速复制译文，提高阅读效率
* **全文翻译**：悬浮球一键翻译整个网页，无需刷新页面
### 隐私与定制 [#隐私与定制]
* **隐私保护**：所有数据本地存储，代码开源透明
* **高度定制**：丰富的自定义选项，满足不同场景需求
* **完全免费**：开源免费，非商业化项目
## 📦 安装方式 [#-安装方式]
| 浏览器 | 安装方式 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chrome** | [Chrome 应用商店](https://chromewebstore.google.com/detail/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/djnlaiohfaaifbibleebjggkghlmcpcj?hl=zh-CN\&authuser=0) \| [国内镜像](https://www.crxsoso.com/webstore/detail/djnlaiohfaaifbibleebjggkghlmcpcj) |
| **Edge** | [Edge 应用商店](https://microsoftedge.microsoft.com/addons/detail/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/kakgmllfpjldjhcnkghpplmlbnmcoflp?hl=zh-CN) |
| **Firefox** | [Firefox 附加组件商店](https://addons.mozilla.org/zh-CN/firefox/addon/%E6%B5%81%E7%95%85%E9%98%85%E8%AF%BB/) |
## 🚀 配置方法 [#-配置方法]
### 从 ZipFlow 控制台导入配置（推荐） [#从-zipflow-控制台导入配置推荐]
当浏览器安装了流畅阅读插件后，打开 ZipFlow 控制台->令牌管理页面会弹出添加流畅阅读的提示
选择模型后点击一键填充到FluentRead，会弹出确认窗口，检查对应的信息是否正确
确认导入后在流畅阅读中的ZipFlow配置便会启用
### 在流畅阅读中手动填写配置 [#在流畅阅读中手动填写配置]
| 配置项 | 内容 |
| --------- | ------------------ |
| 翻译服务 | ZipFlow |
| 访问令牌 | ZipFlow 密钥 |
| ZipFlow接口 | ZipFlow部署地址（不带/v1） |
| 模型 | 列表中选择，或者自定义模型 |
| 自定义模型 | 模型名称 |
# LangBot - 即时通信机器人开发平台 (/zh/apps/langbot)
LangBot 是一个开源的即时通信机器人开发平台，支持多种即时通信平台，如飞书、钉钉、微信、QQ、Telegram、Discord、Slack 等。接入全球主流的 AI 模型，支持知识库、Agent、MCP等多种 AI 应用能力，并完美适配 ZipFlow。
* 官网地址：[https://langbot.app/](https://langbot.app/)
* 下载地址：[https://github.com/langbot-app/LangBot/releases](https://github.com/langbot-app/LangBot/releases)
* 官方文档：[https://docs.langbot.app/](https://docs.langbot.app/)
* 开源地址：[https://github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot)
## 接入 ZipFlow [#接入-zipflow]
LangBot 支持接入本地部署的 ZipFlow 和第三方使用 ZipFlow 搭建的 ZipFlow 服务。
### 使用方式 [#使用方式]
1. 从 ZipFlow 中获取 API key
若是本地部署的 ZipFlow 请自行配置 API 地址（可参考[容器网络连接](https://docs.langbot.app/zh/workshop/network-details.html)），若使用第三方 ZipFlow 服务，可在页面上复制地址。注意，地址后需要添加`/v1`。
2. 在 LangBot 中添加模型，选择使用 ZipFlow 供应商，填写对应的 API key 和 API 地址
3. 在流水线中选择使用模型
4. 在对话调试中对话或与绑定至流水线的机器人对话即可使用
部署配置机器人请参考[部署机器人](https://docs.langbot.app/zh/deploy/platforms/readme.html)。
### 使用 LangBot 知识库 [#使用-langbot-知识库]
LangBot 支持使用 ZipFlow 的嵌入模型，并将其作为知识库的向量模型。
1. 在 LangBot 中添加嵌入模型，选择使用 ZipFlow 供应商
2. 在新建知识库时选用嵌入模型
更多使用方式请查看 LangBot 官方文档：[https://docs.langbot.app/](https://docs.langbot.app/)
# LunaTranslator - 开源 GalGame 翻译器 (/zh/apps/luna-translator)
在 ZipFlow 控制台的系统设置->聊天设置中，可添加如下快捷选项，便于在令牌管理页一键填充到 LunaTranslator：
```json
{ "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" }
```
LunaTranslator 是一款开源免费的视觉小说（GalGame）翻译器，致力于提供母语级别的视觉小说游玩体验。
* 项目地址：[https://github.com/HIllya51/LunaTranslator](https://github.com/HIllya51/LunaTranslator)
* 项目文档：[https://docs.lunatranslator.org/zh/README.html](https://docs.lunatranslator.org/zh/README.html)
## 功能支持 [#功能支持]
* **HOOK** 主要使用HOOK提取游戏文本，几乎适配了所有的常见和冷门的视觉小说
* **内嵌翻译** 部分游戏还可以直接内嵌翻译到游戏中，以获取沉浸式体验
* **HOOK模拟器** 对NS/PSP/PSV/PS2上的大部分游戏，支持HOOK模拟器直接读取游戏文本
* **OCR** 内置较高精度的OCR模型，并支持许多其他在线&离线OCR引擎，以便灵活的读取任意文本
* **丰富的翻译接口** 支持几乎所有翻译引擎，包括大语言模型翻译、离线翻译等
* **语言学习** 支持日语分词及假名注音，支持AnkiConnect，支持Yomitan插件
* **语音合成** 支持大量在线&离线语音合成引擎
* **语音识别** 在Windows 10和Windows 11上，可以使用Windows语音识别。
## 安装方式 [#安装方式]
在 [LunaTranslator 文档- 下载 & 启动 & 更新](https://docs.lunatranslator.org/zh/README.html) 进行下载安装
## 在 LunaTranslator 接入 ZipFlow [#在-lunatranslator-接入-zipflow]
LunaTranslator 支持接入本地部署的 ZipFlow 和第三方使用 ZipFlow 搭建的 ZipFlow 服务。
### 一键配置 [#一键配置]
1. 在 ZipFlow 控制台的`系统设置`->`聊天设置`中，添加如下快捷选项：
```json
{ "LunaTranslator": "lunatranslator://llmapi/base64?data={cheryConfig}" }
```
2. 在 **`ZipFlow`** -> `控制台` -> `令牌管理` 选项卡中选择要使用在 LunaTranslator 的令牌，点击聊天按钮旁的下拉选项，选择 `LunaTranslator`,将会跳转到 LunaTranslator 并自动配置 API 地址与 API Key
3. 在 **`LunaTranslator`** -> `设置` -> `翻译设置` -> `大模型` 中将出现一个新增的大模型接口配置，点击编辑
4. 点击 **model** 下拉框旁的刷新按钮，获取 ZipFlow 平台的模型列表，选择或输入模型名称，完成后点击确定保存
5. 检查 **new\_api** 大模型接口配置旁边的开关按钮是否打开，若未启用则启用接口即可开始使用
### 手动配置 [#手动配置]
1. 在 **`ZipFlow`** -> `控制台` -> `令牌管理` 选项卡中获取 API Key
2. 在 **`LunaTranslator`** -> `设置` - `翻译设置` -> `大模型` 中选择添加
3. 复制 **大模型通用接口** 模板，新增接口
4. 在 **新增的接口** 中，填写对应的 API 地址和 API Key
5. 点击 **model** 下拉框旁的刷新按钮，获取 ZipFlow 平台的模型列表，选择或输入模型名称，完成后点击确定保存
6. 点击 **ZipFlow** 旁边的开关按钮，启用接口即可开始使用
更多使用方式请查看 LunaTranslator 官方文档:[LunaTranslator 文档 - 大模型翻译接口](https://docs.lunatranslator.org/zh/guochandamoxing.html)
# Anthropic 对话格式（Messages） (/zh/api/anthropic-chat)
* [Anthropic Messages](https://docs.anthropic.com/en/api/messages)
* [Anthropic Streaming Messages](https://docs.anthropic.com/en/api/messages-streaming)
## 📝 简介 [#-简介]
给定一组包含文本和/或图像内容的结构化输入消息列表，模型将生成对话中的下一条消息。Messages API 可用于单次查询或无状态的多轮对话。
## 💡 请求示例 [#-请求示例]
### 基础文本对话 ✅ [#基础文本对话-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}'
```
**响应示例:**
```json
{
"content": [
{
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2095,
"output_tokens": 503
}
}
```
### 图像分析对话 ✅ [#图像分析对话-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "这张图片里有什么?"
}
]
}
]
}'
```
**响应示例:**
```json
{
"content": [
{
"text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松，眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 3050,
"output_tokens": 892
}
}
```
### 工具调用 ✅ [#工具调用-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": "今天北京的天气怎么样?"
}
],
"tools": [
{
"name": "get_weather",
"description": "获取指定位置的当前天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,如:北京"
}
},
"required": ["location"]
}
}
]
}'
```
**响应示例:**
```json
{
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "北京" }
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "tool_use",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2156,
"output_tokens": 468
}
}
```
### 流式响应 ✅ [#流式响应-]
```bash
curl https://api.zipflow.xyz/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $ZIPFLOW_API_KEY" \
--data \
'{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": "讲个故事"
}
],
"stream": true
}'
```
**响应示例:**
```json
{
"type": "message_start",
"message": {
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"type": "message"
}
}
{
"type": "content_block_start",
"index": 0,
"content_block": {
"type": "text"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "从前"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "有一只"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "小兔子..."
}
}
{
"type": "content_block_stop",
"index": 0
}
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"usage": {
"input_tokens": 2045,
"output_tokens": 628
}
}
}
{
"type": "message_stop"
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/messages
```
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
x-api-key: $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。您可以通过控制台获取 API 密钥，每个密钥仅限于一个工作区使用。
### 请求头参数 [#请求头参数]
#### `anthropic-beta` [#anthropic-beta]
* 类型：字符串
* 必需：否
指定要使用的 beta 版本，支持用逗号分隔的列表如 `beta1,beta2`，或多次指定该请求头。
#### `anthropic-version` [#anthropic-version]
* 类型：字符串
* 必需：是
指定要使用的 API 版本。
### 请求体参数 [#请求体参数]
#### `max_tokens` [#max_tokens]
* 类型：整数
* 必需：是
生成的最大 token 数量。不同模型有不同的限制，详见模型文档。范围 `x > 1`。
#### `messages` [#messages]
* 类型：对象数组
* 必需：是
输入消息列表。模型被训练为在用户和助手之间交替进行对话。创建新消息时，您可以使用 messages 参数指定之前的对话轮次，模型将生成对话中的下一条消息。连续的用户或助手消息会被合并为单个轮次。
每个消息必须包含 `role` 和 `content` 字段。您可以指定单个用户角色消息，或包含多个用户和助手消息。如果最后一条消息使用助手角色，响应内容将直接从该消息的内容继续，这可以用来约束模型的响应。
**单条用户消息示例:**
```json
[{"role": "user", "content": "Hello, Claude"}]
```
**多轮对话示例:**
```json
[
{"role": "user", "content": "你好。"},
{"role": "assistant", "content": "你好！我是 Claude。有什么可以帮你的吗？"},
{"role": "user", "content": "请用简单的话解释什么是 LLM？"}
]
```
**部分填充的响应示例:**
```json
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
```
每个消息的 content 可以是字符串或内容块数组。使用字符串相当于一个 "text" 类型的内容块数组的简写。以下两种写法等效：
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{
"role": "user",
"content": [{"type": "text", "text": "Hello, Claude"}]
}
```
从 Claude 3 模型开始，您还可以发送图片内容块：
```json
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "这张图片里有什么?"
}
]
}
```
> 目前支持的图片格式包括: base64, image/jpeg、image/png、image/gif 和 image/webp。
##### `messages.role` [#messagesrole]
* 类型：枚举字符串
* 必需：是
* 可选值：user, assistant
注意：Messages API 中没有 "system" 角色，如果需要系统提示，请使用顶层的 system 参数。
##### `messages.content` [#messagescontent]
* 类型：字符串或对象数组
* 必需：是
消息内容可以是以下几种类型之一：
###### 文本内容 (Text) [#文本内容-text]
```json
{
"type": "text", // 必需，枚举值: "text"
"text": "Hello, Claude", // 必需，最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
}
```
###### 图片内容 (Image) [#图片内容-image]
```json
{
"type": "image", // 必需，枚举值: "image"
"source": { // 必需
"type": "base64", // 必需，枚举值: "base64"
"media_type": "image/jpeg", // 必需，支持: image/jpeg, image/png, image/gif, image/webp
"data": "/9j/4AAQSkZJRg..." // 必需，base64 编码的图片数据
},
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
}
```
###### 工具使用 (Tool Use) [#工具使用-tool-use]
```json
{
"type": "tool_use", // 必需，枚举值: "tool_use"，默认值
"id": "toolu_xyz...", // 必需，工具使用的唯一标识符
"name": "get_weather", // 必需，工具名称，最小长度: 1
"input": { // 必需，工具的输入参数对象
// 工具输入参数，具体格式由工具的 input_schema 定义
},
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
}
```
###### 工具结果 (Tool Result) [#工具结果-tool-result]
```json
{
"type": "tool_result", // 必需，枚举值: "tool_result"
"tool_use_id": "toolu_xyz...", // 必需
"content": "结果内容", // 必需，可以是字符串或内容块数组
"is_error": false, // 可选，布尔值
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
}
```
当 content 为内容块数组时，每个内容块可以是文本或图片：
```json
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": [
{
"type": "text", // 必需，枚举值: "text"
"text": "分析结果", // 必需，最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
},
{
"type": "image", // 必需，枚举值: "image"
"source": { // 必需
"type": "base64", // 必需，枚举值: "base64"
"media_type": "image/jpeg",
"data": "..."
},
"cache_control": {
"type": "ephemeral"
}
}
]
}
```
###### 文档 (Document) [#文档-document]
```json
{
"type": "document", // 必需，枚举值: "document"
"source": { // 必需
// 文档源数据
},
"cache_control": {
"type": "ephemeral" // 可选，枚举值: "ephemeral"
}
}
```
注意：
1. 每种类型都可以包含可选的 `cache_control` 字段，用于控制内容的缓存行为
2. 文本内容的最小长度为 1
3. 所有类型的 type 字段都是必需的枚举字符串
4. 工具结果的 content 字段支持字符串或包含文本/图片的内容块数组
#### `model` [#model]
* 类型：字符串
* 必需：是
要使用的模型名称，详见模型文档。范围 `1 - 256` 个字符。
#### `metadata` [#metadata]
* 类型：对象
* 必需：否
描述请求元数据的对象。包含以下可选字段：
* `user_id`: 与请求关联的用户的外部标识符。应该是 uuid、哈希值或其他不透明标识符。不要包含任何标识信息如姓名、邮箱或电话号码。最大长度：256。
#### `stop_sequences` [#stop_sequences]
* 类型：字符串数组
* 必需：否
自定义的停止生成的文本序列。
#### `stream` [#stream]
* 类型：布尔值
* 必需：否
是否使用服务器发送事件 (SSE) 来增量返回响应内容。
#### `system` [#system]
* 类型：字符串
* 必需：否
系统 prompt，为 Claude 提供背景和指令。这是一种为模型提供上下文和特定目标或角色的方式。注意这与消息中的 role 不同，Messages API 中没有 "system" 角色。
#### `temperature` [#temperature]
* 类型：数字
* 必需：否
* 默认值：1.0
控制生成随机性，0.0 - 1.0。范围 `0 < x < 1`。建议对于分析性/选择题类任务使用接近 0.0 的值，对于创造性和生成性任务使用接近 1.0 的值。
注意：即使 temperature 设置为 0.0，结果也不会完全确定。
#### 🆕 `thinking` [#-thinking]
* 类型：对象
* 必需：否
配置 Claude 的扩展思考功能。启用时，响应将包含展示 Claude 在给出最终答案前的思考过程的内容块。需要至少 1,024 个 token 的预算，并计入您的 max\_tokens 限制。
可以设置为以下两种模式之一：
##### 1. 启用模式 [#1-启用模式]
```json
{
"type": "enabled",
"budget_tokens": 2048
}
```
* `type`: 必需，枚举值: "enabled"
* `budget_tokens`: 必需，整数。决定 Claude 可以用于内部推理过程的 token 数量。更大的预算可以让模型对复杂问题进行更深入的分析，提高响应质量。必须 ≥1024 且小于 max\_tokens。范围 `x > 1024`。
##### 2. 禁用模式 [#2-禁用模式]
```json
{
"type": "disabled"
}
```
* `type`: 必需，枚举值: "disabled"
#### `tool_choice` [#tool_choice]
* 类型：对象
* 必需：否
控制模型如何使用提供的工具。可以是以下三种类型之一：
##### 1. Auto 模式 (自动选择) [#1-auto-模式-自动选择]
```json
{
"type": "auto", // 必需，枚举值: "auto"
"disable_parallel_tool_use": false // 可选，默认 false。如果为 true，模型最多只会使用一个工具
}
```
##### 2. Any 模式 (任意工具) [#2-any-模式-任意工具]
```json
{
"type": "any", // 必需，枚举值: "any"
"disable_parallel_tool_use": false // 可选，默认 false。如果为 true，模型将恰好使用一个工具
}
```
##### 3. Tool 模式 (指定工具) [#3-tool-模式-指定工具]
```json
{
"type": "tool", // 必需，枚举值: "tool"
"name": "get_weather", // 必需，指定要使用的工具名称
"disable_parallel_tool_use": false // 可选，默认 false。如果为 true，模型将恰好使用一个工具
}
```
注意：
1. Auto 模式：模型可以自行决定是否使用工具
2. Any 模式：模型必须使用工具，但可以选择任何可用的工具
3. Tool 模式：模型必须使用指定的工具
#### `tools` [#tools]
* 类型：对象数组
* 必需：否
定义模型可能使用的工具。工具可以是自定义工具或内置工具类型：
##### 1. 自定义工具（Tool） [#1-自定义工具tool]
每个自定义工具定义包含：
* `type`: 可选，枚举值: "custom"
* `name`: 工具名称，必需，1-64 个字符
* `description`: 工具描述，建议尽可能详细
* `input_schema`: 工具输入的 JSON Schema 定义，必需
* `cache_control`: 缓存控制，可选，type 为 "ephemeral"
示例：
```json
[
{
"type": "custom",
"name": "get_weather",
"description": "获取指定位置的当前天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,如:北京"
}
},
"required": ["location"]
}
}
]
```
##### 2. 计算机工具 (ComputerUseTool) [#2-计算机工具-computerusetool]
```json
{
"type": "computer_20241022", // 必需
"name": "computer", // 必需，枚举值: "computer"
"display_width_px": 1024, // 必需，显示宽度(像素)
"display_height_px": 768, // 必需，显示高度(像素)
"display_number": 0, // 可选，X11 显示编号
"cache_control": {
"type": "ephemeral" // 可选
}
}
```
##### 3. Bash 工具 (BashTool) [#3-bash-工具-bashtool]
```json
{
"type": "bash_20241022", // 必需
"name": "bash", // 必需，枚举值: "bash"
"cache_control": {
"type": "ephemeral" // 可选
}
}
```
##### 4. 文本编辑器工具 (TextEditor) [#4-文本编辑器工具-texteditor]
```json
{
"type": "text_editor_20241022", // 必需
"name": "str_replace_editor", // 必需，枚举值: "str_replace_editor"
"cache_control": {
"type": "ephemeral" // 可选
}
}
```
当模型使用工具时，会返回 tool\_use 内容块：
```json
[
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "北京" }
}
]
```
您可以执行工具并通过 tool\_result 内容块返回结果：
```json
[
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"content": "北京当前天气晴朗，温度 25°C"
}
]
```
#### `top_k` [#top_k]
* 类型：整数
* 必需：否
* 范围：x > 0
从 token 的前 K 个选项中采样。用于移除低概率的"长尾"响应。建议仅在高级用例中使用，通常只需要调整 temperature。
#### `top_p` [#top_p]
* 类型：数字
* 必需：否
* 范围：0 \< x \< 1
使用 nucleus 采样。计算每个后续 token 按概率降序排列的累积分布，在达到 top\_p 指定的概率时截断。建议仅调整 temperature 或 top\_p 其中之一，不要同时使用。
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
返回一个聊天补全对象，包含以下字段：
#### `content` [#content]
* 类型：对象数组
* 必需：是
模型生成的内容，由多个内容块组成。每个内容块都有一个确定其形状的 type。内容块可以是以下类型之一：
##### 文本内容块 (Text) [#文本内容块-text]
```json
{
"type": "text", // 必需，枚举值: "text"，默认值
"text": "你好，我是 Claude。" // 必需，最大长度: 5000000，最小长度: 1
}
```
##### 工具使用内容块 (Tool Use) [#工具使用内容块-tool-use]
```json
{
"type": "tool_use", // 必需，枚举值: "tool_use"，默认值
"id": "toolu_xyz...", // 必需，工具使用的唯一标识符
"name": "get_weather", // 必需，工具名称，最小长度: 1
"input": { // 必需，工具的输入参数对象
// 工具输入参数，具体格式由工具的 input_schema 定义
}
}
```
示例：
```json
// 文本内容示例
[{"type": "text", "text": "你好，我是 Claude。"}]
// 工具使用示例
[{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "北京" }
}]
// 混合内容示例
[
{"type": "text", "text": "根据天气查询结果："},
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "北京" }
}
]
```
如果请求的最后一条消息是助手角色，响应内容会直接从该消息继续。例如：
```json
// 请求
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
// 响应
[{"type": "text", "text": "B)"}]
```
#### `id` [#id]
* 类型：字符串
* 必需：是
响应的唯一标识符。
#### `model` [#model-1]
* 类型：字符串
* 必需：是
使用的模型名称。
#### `role` [#role]
* 类型：枚举字符串
* 必需：是
* 默认值：assistant
生成消息的会话角色，始终为 "assistant"。
#### `stop_reason` [#stop_reason]
* 类型：枚举字符串或 null
* 必需：是
停止生成的原因，可能的值包括：
* `"end_turn"`: 模型达到自然停止点
* `"max_tokens"`: 超过请求的 max\_tokens 或模型的最大限制
* `"stop_sequence"`: 生成了自定义停止序列之一
* `"tool_use"`: 模型调用了一个或多个工具
在非流式模式下，此值始终非空。在流式模式下，在 message\_start 事件中为 null，其他情况下非空。
#### `stop_sequence` [#stop_sequence]
* 类型：字符串或 null
* 必需：是
生成的自定义停止序列。如果模型遇到了 stop\_sequences 参数中指定的某个序列，这个字段将包含该匹配的停止序列。如果不是因为停止序列而停止，则为 null。
#### `type` [#type]
* 类型：枚举字符串
* 必需：是
* 默认值：message
* 可选值：message
对象类型，对于 Messages 始终为 "message"。
#### `usage` [#usage]
* 类型：对象
* 必需：是
计费和限流相关的使用量统计。包含以下字段：
* `input_tokens`: 使用的输入 token 数量，必需，范围 x > 0
* `output_tokens`: 使用的输出 token 数量，必需，范围 x > 0
* `cache_creation_input_tokens`: 创建缓存条目使用的输入 token 数量(如果适用)，必需，范围 x > 0
* `cache_read_input_tokens`: 从缓存读取的输入 token 数量(如果适用)，必需，范围 x > 0
注意：由于 API 在内部会对请求进行转换和解析，token 计数可能与请求和响应的实际可见内容不完全对应。例如，即使是空字符串响应，output\_tokens 也会是非零值。
### 错误响应 [#错误响应]
当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。
#### 常见错误状态码 [#常见错误状态码]
* `401 Unauthorized`: API 密钥无效或未提供
* `400 Bad Request`: 请求参数无效
* `429 Too Many Requests`: 超出 API 调用限制
* `500 Internal Server Error`: 服务器内部错误
错误响应示例:
```json
{
"error": {
"type": "invalid_request_error",
"message": "Invalid API key provided",
"code": "invalid_api_key"
}
}
```
主要错误类型:
* `invalid_request_error`: 请求参数错误
* `authentication_error`: 认证相关错误
* `rate_limit_error`: 请求频率超限
* `server_error`: 服务器内部错误
# Cohere 重排序格式（Rerank） (/zh/api/cohere-rerank)
cohere 的 Rerank 模型接口和 [Jina的Rerank模型接口格式](/zh/api/jinaai-rerank) 是一样的。
[Cohere Rerank](https://docs.cohere.com/reference/rerank)
## 📝 简介 [#-简介]
给定查询和文本列表，重排序API将根据与查询的相关性对文本进行排序。每个文本都会被分配一个相关性分数，从而产生一个有序的数组结果。此功能特别适用于搜索和检索应用，可以优化文档的排序，帮助用户更快找到相关信息。
## 💡 请求示例 [#-请求示例]
### 基础重排序请求 ✅ [#基础重排序请求-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "rerank-v3.5",
"query": "什么是美国的首都？",
"documents": [
"内华达州的首府是卡森城。",
"北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
"华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
"英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
"自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
],
"top_n": 3
}'
```
**响应示例:**
```json
{
"results": [
{
"index": 2,
"relevance_score": 0.999071
},
{
"index": 0,
"relevance_score": 0.32713068
},
{
"index": 1,
"relevance_score": 0.1867867
}
],
"id": "07734bd2-2473-4f07-94e1-0d9f0e6843cf",
"meta": {
"api_version": {
"version": "2",
"is_experimental": false
},
"billed_units": {
"search_units": 1
}
}
}
```
### 使用结构化数据 ✅ [#使用结构化数据-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "rerank-v3.5",
"query": "寻找适合初学者的高性价比单反相机",
"documents": [
"型号: Canon EOS 800D\n价格: 4299元\n功能: 2410万像素, 光学取景器, Wi-Fi\n适合人群: 初学者, 爱好者",
"型号: Nikon D3500\n价格: 3099元\n功能: 2416万像素, 光学取景器, 长达1550张的电池续航\n适合人群: 新手, 学生",
"型号: Sony A7III\n价格: 12999元\n功能: 2420万像素, 全画幅, 4K视频\n适合人群: 专业摄影师, 视频创作者"
],
"max_tokens_per_doc": 512
}'
```
**响应示例:**
```json
{
"results": [
{
"index": 1,
"relevance_score": 0.918472
},
{
"index": 0,
"relevance_score": 0.854321
},
{
"index": 2,
"relevance_score": 0.423156
}
],
"id": "8f734bd2-2473-4f07-94e1-0d9f0e68ebfa",
"meta": {
"api_version": {
"version": "2"
},
"billed_units": {
"search_units": 1
}
}
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/rerank
```
根据与查询的相关性对文本列表进行重新排序。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。
### 请求头参数 [#请求头参数]
#### `X-Client-Name` [#x-client-name]
* 类型：字符串
* 必需：否
* 说明：发起请求的项目名称。
### 请求体参数 [#请求体参数]
#### `model` [#model]
* 类型：字符串
* 必需：是
* 说明：要使用的模型标识符，例如 rerank-v3.5。
#### `query` [#query]
* 类型：字符串
* 必需：是
* 说明：搜索查询文本。这是用户输入的问题或查询内容。
#### `documents` [#documents]
* 类型：字符串数组
* 必需：是
* 说明：将与查询进行比较的文本列表。为获得最佳性能，建议单个请求中不要发送超过1,000个文档。
* 注意事项：
* 长文档将自动截断为 max\_tokens\_per\_doc 指定的值
* 结构化数据应格式化为YAML字符串以获得最佳性能
#### `top_n` [#top_n]
* 类型：整数
* 必需：否
* 说明：限制返回的重排结果数量。如果不指定，将返回所有重排结果。
#### `max_tokens_per_doc` [#max_tokens_per_doc]
* 类型：整数
* 必需：否
* 默认值：4096
* 说明：长文档将自动截断为指定的令牌数量。
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
返回一个包含排序后文档列表的对象。
#### `results` [#results]
* 类型：对象数组
* 说明：排序后的文档列表，按相关性降序排列
* 属性：
* `index`: 整数，对应于原始文档列表中文档的索引
* `relevance_score`: 浮点数，相关性分数范围为\[0, 1]。接近1的分数表示与查询高度相关，接近0的分数表示相关性较低
#### `id` [#id]
* 类型：字符串
* 说明：请求的唯一标识符
#### `meta` [#meta]
* 类型：对象
* 说明：包含关于请求的元数据
* 属性：
* `api_version`: 对象，包含API版本信息
* `version`: 字符串，API版本号
* `is_deprecated`: 布尔值，是否已弃用
* `is_experimental`: 布尔值，是否为实验性功能
* `billed_units`: 对象，包含计费信息
* `search_units`: 浮点数，计费的搜索单位数
* `tokens`: 对象，包含令牌使用统计
* `input_tokens`: 浮点数，作为模型输入的令牌数
* `output_tokens`: 浮点数，模型产生的令牌数
#### `warnings` [#warnings]
* 类型：字符串数组
* 必需：否
* 说明：API返回的警告信息
### 错误响应 [#错误响应]
当请求出现问题时，API可能返回以下HTTP状态码及相应错误：
* `400 Bad Request`: 请求格式或参数错误
* `401 Unauthorized`: 未提供有效的API密钥
* `403 Forbidden`: 没有权限访问此资源
* `404 Not Found`: 请求的资源不存在
* `422 Unprocessable Entity`: 请求格式正确但包含语义错误
* `429 Too Many Requests`: 请求频率超过限制
* `500 Internal Server Error`: 服务器内部错误
* `503 Service Unavailable`: 服务暂时不可用
## 🌟 最佳实践 [#-最佳实践]
### 文档准备建议 [#文档准备建议]
1. **文档长度**：每个文档保持简洁明了，避免过长。长文档会被自动截断。
2. **结构化数据**：将结构化数据格式化为YAML字符串，以获得最佳性能。例如：
```yaml
title: 产品名称
price: 9999元
features:
- 特性1
- 特性2
```
3. **文档数量**：单次请求中不要超过1,000个文档，以获得最佳性能。
### 查询优化 [#查询优化]
1. **明确具体**：制定明确、具体的查询，以获得更准确的排序结果。
2. **避免模糊查询**：尽量避免过于模糊或通用的查询词，这可能导致相关性分数差异不明显。
### 理解相关性分数 [#理解相关性分数]
相关性分数是归一化到\[0, 1]范围内的值：
* 接近1的分数表示与查询高度相关
* 接近0的分数表示相关性低
注意：不能简单地认为分数0.9的文档比分数0.45的文档相关性高2倍。相关性分数是一个相对指标，用于排序，而非绝对比较。
# Deepseek reasoning 对话格式（Reasoning Content） (/zh/api/deepseek-reasoning-chat)
[推理模型 (deepseek-reasoner)](https://api-docs.deepseek.com/zh-cn/guides/reasoning_model)
## 📝 简介 [#-简介]
Deepseek-reasoner 是 DeepSeek 推出的推理模型。在输出最终回答之前，模型会先输出一段思维链内容，以提升最终答案的准确性。API 向用户开放 deepseek-reasoner 思维链的内容，以供用户查看、展示、蒸馏使用。
## 💡 请求示例 [#-请求示例]
### 基础文本对话 ✅ [#基础文本对话-]
```bash
curl https://api.deepseek.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "deepseek-reasoner",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
],
"max_tokens": 4096
}'
```
**响应示例:**
```json
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1677652288,
"model": "deepseek-reasoner",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"reasoning_content": "让我一步步思考:\n1. 我们需要比较9.11和9.8的大小\n2. 两个数都是小数,我们可以直接比较\n3. 9.8 = 9.80\n4. 9.11 < 9.80\n5. 所以9.8更大",
"content": "9.8 is greater than 9.11."
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 15,
"total_tokens": 25
}
}
```
### 流式响应 ✅ [#流式响应-]
```bash
curl https://api.deepseek.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "deepseek-reasoner",
"messages": [
{
"role": "user",
"content": "9.11 and 9.8, which is greater?"
}
],
"stream": true
}'
```
**流式响应示例:**
```jsonl
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"role":"assistant","reasoning_content":"让我"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":"一步步"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"reasoning_content":"思考:"},"finish_reason":null}]}
// ... 更多思维链内容 ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":"9.8"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{"content":" is greater"},"finish_reason":null}]}
// ... 更多最终答案内容 ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"deepseek-reasoner","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/chat/completions
```
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$DEEPSEEK_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### `messages` [#messages]
* 类型：数组
* 必需：是
到目前为止包含对话的消息列表。请注意,如果您在输入的 messages 序列中传入了 reasoning\_content，API 会返回 400 错误。
#### `model` [#model]
* 类型：字符串
* 必需：是
* 值：deepseek-reasoner
要使用的模型 ID。目前仅支持 deepseek-reasoner。
#### `max_tokens` [#max_tokens]
* 类型：整数
* 必需：否
* 默认值：4096
* 最大值：8192
最终回答的最大长度（不含思维链输出）。请注意，思维链的输出最多可以达到 32K tokens。
#### `stream` [#stream]
* 类型：布尔值
* 必需：否
* 默认值：false
是否使用流式响应。
### 不支持的参数 [#不支持的参数]
以下参数当前不支持:
* temperature
* top\_p
* presence\_penalty
* frequency\_penalty
* logprobs
* top\_logprobs
注意:为了兼容已有软件,设置 temperature、top\_p、presence\_penalty、frequency\_penalty 参数不会报错,但也不会生效。设置 logprobs、top\_logprobs 会报错。
### 支持的功能 [#支持的功能]
* 对话补全
* 对话前缀续写 (Beta)
### 不支持的功能 [#不支持的功能]
* Function Call
* Json Output
* FIM 补全 (Beta)
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
返回一个聊天补全对象，如果请求被流式传输，则返回聊天补全块对象的流式序列。
#### `id` [#id]
* 类型：字符串
* 说明：响应的唯一标识符
#### `object` [#object]
* 类型：字符串
* 说明：对象类型,值为 "chat.completion"
#### `created` [#created]
* 类型：整数
* 说明：响应创建时间戳
#### `model` [#model-1]
* 类型：字符串
* 说明：使用的模型名称,值为 "deepseek-reasoner"
#### `choices` [#choices]
* 类型：数组
* 说明：包含生成的回复选项
* 属性:
* `index`: 选项索引
* `message`: 包含角色、思维链内容和最终回答的消息对象
* `role`: 角色,值为 "assistant"
* `reasoning_content`: 思维链内容
* `content`: 最终回答内容
* `finish_reason`: 完成原因
#### `usage` [#usage]
* 类型：对象
* 说明：token 使用统计
* 属性:
* `prompt_tokens`: 提示使用的 token 数
* `completion_tokens`: 补全使用的 token 数
* `total_tokens`: 总 token 数
## 📝 上下文拼接说明 [#-上下文拼接说明]
在每一轮对话过程中，模型会输出思维链内容（reasoning\_content）和最终回答（content）。在下一轮对话中，之前轮输出的思维链内容不会被拼接到上下文中，如下图所示：
如果您在输入的 messages 序列中，传入了reasoning\_content，API 会返回 400 错误。因此，请删除 API 响应中的 reasoning\_content 字段，再发起 API 请求，方法如下方使用示例所示。
使用示例:
```python
from openai import OpenAI
client = OpenAI(api_key="", base_url="https://api.deepseek.com")
# 第一轮对话
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages
)
reasoning_content = response.choices[0].message.reasoning_content
content = response.choices[0].message.content
# 第二轮对话 - 只拼接最终回答content
messages.append({'role': 'assistant', 'content': content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages
)
```
流式响应示例:
```python
# 第一轮对话
messages = [{"role": "user", "content": "9.11 and 9.8, which is greater?"}]
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages,
stream=True
)
reasoning_content = ""
content = ""
for chunk in response:
if chunk.choices[0].delta.reasoning_content:
reasoning_content += chunk.choices[0].delta.reasoning_content
else:
content += chunk.choices[0].delta.content
# 第二轮对话 - 只拼接最终回答content
messages.append({"role": "assistant", "content": content})
messages.append({'role': 'user', 'content': "How many Rs are there in the word 'strawberry'?"})
response = client.chat.completions.create(
model="deepseek-reasoner",
messages=messages,
stream=True
)
```
# 视频生成 API (/zh/api/generate-video)
调用视频生成接口生成视频，支持多种视频生成服务：
* **可灵AI (Kling)**: [API文档](https://app.klingai.com/cn/dev/document-api/apiReference/commonInfo)
* **即梦 (Jimeng)**: [API文档](https://www.volcengine.com/docs/85621/1538636)
* **Gemini**: Google的视频生成服务
* **Vidu**: 高质量视频生成服务
## ZipFlow 视频生成格式 [#zipflow-视频生成格式]
### API 端点 [#api-端点]
```
POST /v1/video/generations
```
### 请求头 [#请求头]
| 参数 | 类型 | 必填 | 描述 |
| ------------- | ------ | -- | ------------------------ |
| Authorization | string | 是 | 用户认证令牌 (Bearer: sk-xxxx) |
| Content-Type | string | 是 | application/json |
### 请求参数 [#请求参数]
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | -- | -------------------------------------------------------- |
| model | string | 是 | 模型/风格ID |
| prompt | string | 是 | 文本提示词 |
| duration | number | 否 | 视频时长（秒） |
| fps | integer | 否 | 视频帧率 |
| height | integer | 否 | 视频高度 |
| width | integer | 否 | 视频宽度 |
| image | string | 否 | 图片输入（URL/Base64） |
| metadata | object | 否 | 供应商特定/自定义参数（如 negative\_prompt, style, quality\_level 等） |
| n | integer | 否 | 生成视频数量 |
| response\_format | string | 否 | 响应格式 |
| seed | integer | 否 | 随机种子 |
| user | string | 否 | 用户标识符 |
### 请求示例 [#请求示例]
#### 可灵AI 示例 [#可灵ai-示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-v1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"duration": 5,
"metadata": {
"seed": 20231234,
"negative_prompt": "模糊",
"image_tail": "https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png"
}
}'
```
#### 即梦AI 示例 [#即梦ai-示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "一个穿着宇航服的宇航员在月球上行走",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": [
"https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg"
],
"aspect_ratio": "16:9"
}
}'
```
#### Vidu 渠道示例 [#vidu-渠道示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png",
"duration": 5,
"metadata": {
"duration": 5,
"seed": 0,
"resolution": "1080p",
"movement_amplitude": "auto",
"bgm": false,
"payload": "",
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
### 响应格式 [#响应格式]
#### 201 - 创建成功 [#201---创建成功]
```json
{
"id": "video_123",
"object": "video",
"model": "kling-v1",
"created_at": 1640995200,
"task_id": "abcd1234efgh",
"status": "processing"
}
```
#### 响应字段说明 [#响应字段说明]
| 字段 | 类型 | 描述 |
| ----------- | ------- | --------------------- |
| id | string | 视频任务ID |
| object | string | 对象类型，固定为 "video" |
| model | string | 使用的模型名称 |
| created\_at | integer | 创建时间戳 |
| task\_id | string | 任务ID，用于查询状态 |
| status | string | 任务状态（processing: 处理中） |
## 错误响应 [#错误响应]
### 400 - 请求参数错误 [#400---请求参数错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - 未授权 [#401---未授权]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - 无权限 [#403---无权限]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 500 - 服务器内部错误 [#500---服务器内部错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
## 支持的模型 [#支持的模型]
### 可灵AI (Kling) [#可灵ai-kling]
* `kling-v1`: 文生视频模型
* `kling-v2-master`: 图生视频模型
### 即梦 (Jimeng) [#即梦-jimeng]
* `jimeng_vgfm_t2v_l20`: 文生视频模型
* `jimeng_vgfm_i2v_l20`: 图生视频模型
### Vidu [#vidu]
* `viduq1`: Vidu高质量视频生成模型
## 最佳实践 [#最佳实践]
1. **提示词优化**: 使用详细、具体的描述词，包含风格、质量要求
2. **图片质量**: 图生视频时使用高分辨率、清晰的图片
3. **参数调优**: 根据需求调整时长、分辨率等参数
4. **错误处理**: 实现适当的重试机制和错误处理
5. **异步处理**: 视频生成是异步任务，需要轮询查询状态
# Google Gemini 对话格式（Generate Content） (/zh/api/google-gemini-chat)
[Google Gemini Generating content API](https://ai.google.dev/api/generate-content)
## 📝 简介 [#-简介]
Google Gemini API 支持使用图片、音频、代码、工具等生成内容。给定输入 GenerateContentRequest 生成模型响应。支持文本生成、视觉理解、音频处理、长上下文、代码执行、JSON 模式、函数调用等多种功能。
## 💡 请求示例 [#-请求示例]
### 基础文本对话 ✅ [#基础文本对话-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[{"text": "Write a story about a magic backpack."}]
}]
}' 2> /dev/null
```
### 图像分析对话 ✅ [#图像分析对话-]
```bash
# 使用临时文件保存base64编码的图片数据
TEMP_B64=$(mktemp)
trap 'rm -f "$TEMP_B64"' EXIT
base64 $B64FLAGS $IMG_PATH > "$TEMP_B64"
# 使用临时文件保存JSON载荷
TEMP_JSON=$(mktemp)
trap 'rm -f "$TEMP_JSON"' EXIT
cat > "$TEMP_JSON" << EOF
{
"contents": [{
"parts":[
{"text": "Tell me about this instrument"},
{
"inline_data": {
"mime_type":"image/jpeg",
"data": "$(cat "$TEMP_B64")"
}
}
]
}]
}
EOF
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d "@$TEMP_JSON" 2> /dev/null
```
### 函数调用 ✅ [#函数调用-]
```bash
cat > tools.json << EOF
{
"function_declarations": [
{
"name": "enable_lights",
"description": "Turn on the lighting system."
},
{
"name": "set_light_color",
"description": "Set the light color. Lights must be enabled for this to work.",
"parameters": {
"type": "object",
"properties": {
"rgb_hex": {
"type": "string",
"description": "The light color as a 6-digit hex string, e.g. ff0000 for red."
}
},
"required": [
"rgb_hex"
]
}
},
{
"name": "stop_lights",
"description": "Turn off the lighting system."
}
]
}
EOF
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d @<(echo '
{
"system_instruction": {
"parts": {
"text": "You are a helpful lighting system bot. You can turn lights on and off, and you can set the color. Do not perform any other tasks."
}
},
"tools": ['$(cat tools.json)'],
"tool_config": {
"function_calling_config": {"mode": "auto"}
},
"contents": {
"role": "user",
"parts": {
"text": "Turn on the lights please."
}
}
}
') 2>/dev/null |sed -n '/"content"/,/"finishReason"/p'
```
### JSON 模式响应 ✅ [#json-模式响应-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [{
"parts":[
{"text": "List 5 popular cookie recipes"}
]
}],
"generationConfig": {
"response_mime_type": "application/json",
"response_schema": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"recipe_name": {"type":"STRING"},
}
}
}
}
}' 2> /dev/null | head
```
### 音频处理 🟡 [#音频处理-]
仅支持通过 `inline_data` 以 base64 方式上传音频，不支持 `file_data.file_uri` 或 File API。
```bash
# 使用File API上传音频数据到API请求
# 使用 base64 inline_data 上传音频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
AUDIO_B64=$(base64 $B64FLAGS "$AUDIO_PATH")
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Please describe this audio file."},
{"inline_data": {"mime_type": "audio/mpeg", "data": "'$AUDIO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### 视频处理 🟡 [#视频处理-]
仅支持通过 `inline_data` 以 base64 方式上传视频，不支持 `file_data.file_uri` 或 File API。
```bash
# 使用File API上传视频数据到API请求
# 使用 base64 inline_data 上传视频数据到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
VIDEO_B64=$(base64 $B64FLAGS "$VIDEO_PATH")
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Transcribe the audio from this video and provide visual descriptions."},
{"inline_data": {"mime_type": "video/mp4", "data": "'$VIDEO_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### PDF处理 🟡 [#pdf处理-]
仅支持通过 `inline_data` 以 base64 方式上传 PDF，不支持 `file_data.file_uri` 或 File API。
```bash
MIME_TYPE=$(file -b --mime-type "${PDF_PATH}")
# 使用 base64 inline_data 上传 PDF 文件到 API 请求
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
PDF_B64=$(base64 $B64FLAGS "$PDF_PATH")
echo $MIME_TYPE
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [
{"text": "Can you add a few more lines to this poem?"},
{"inline_data": {"mime_type": "application/pdf", "data": "'$PDF_B64'"}}
]
}]
}' 2> /dev/null | jq ".candidates[].content.parts[].text"
```
### 聊天对话 ✅ [#聊天对话-]
```bash
curl https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [
{"role":"user",
"parts":[{
"text": "Hello"}]},
{"role": "model",
"parts":[{
"text": "Great to meet you. What would you like to know?"}]},
{"role":"user",
"parts":[{
"text": "I have two dogs in my house. How many paws are in my house?"}]},
]
}' 2> /dev/null | grep "text"
```
### 流式响应 ✅ [#流式响应-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
--no-buffer \
-d '{
"contents": [{
"parts": [{"text": "写一个关于魔法背包的故事"}]
}]
}'
```
### 代码执行 ✅ [#代码执行-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts": [{"text": "计算斐波那契数列的第10项"}]
}],
"tools": [{
"codeExecution": {}
}]
}'
```
### 生成配置 ✅ [#生成配置-]
```bash
curl https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"contents": [{
"parts":[
{"text": "Explain how AI works"}
]
}],
"generationConfig": {
"stopSequences": [
"Title"
],
"temperature": 1.0,
"maxOutputTokens": 800,
"topP": 0.8,
"topK": 10
}
}' 2> /dev/null | grep "text"
```
### 安全设置 ✅ [#安全设置-]
```bash
echo '{
"safetySettings": [
{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH"},
{"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_MEDIUM_AND_ABOVE"}
],
"contents": [{
"parts":[{
"text": "'I support Martians Soccer Club and I think Jupiterians Football Club sucks! Write a ironic phrase about them.'"}]}]}' > request.json
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d @request.json 2> /dev/null
```
### 系统指令 ✅ [#系统指令-]
```bash
curl "https://api.zipflow.xyz/v1beta/models/gemini-2.0-flash:generateContent?key=$ZIPFLOW_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "system_instruction": {
"parts":
{ "text": "You are a cat. Your name is Neko."}},
"contents": {
"parts": {
"text": "Hello there"}}}'
```
## 📮 请求 [#-请求]
### 端点 [#端点]
#### 生成内容 [#生成内容]
```
POST https://api.zipflow.xyz/v1beta/{model=models/*}:generateContent
```
#### 流式生成内容 [#流式生成内容]
```
POST https://api.zipflow.xyz/v1beta/{model=models/*}:streamGenerateContent
```
### 鉴权方法 [#鉴权方法]
在请求URL参数中包含API密钥：
```
?key=$ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 Google AI API 密钥。
### 路径参数 [#路径参数]
#### `model` [#model]
* 类型：字符串
* 必需：是
用于生成补全项的模型名称。
格式：`models/{model}`，例如 `models/gemini-2.0-flash`
### 请求体参数 [#请求体参数]
#### `contents` [#contents]
* 类型：数组
* 必需：是
与模型当前对话的内容。对于单轮查询，这是单个实例。对于聊天等多轮查询，这是包含对话历史记录和最新请求的重复字段。
**Content 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------- | --- | -- | -------------------------------------------- |
| `parts` | 数组 | 是 | 有序的内容部分，构成单个消息 |
| `role` | 字符串 | 否 | 对话中内容的生产者。`user`、`model`、`function` 或 `tool` |
**Part 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------------------- | --- | -- | ---------- |
| `text` | 字符串 | 否 | 纯文本内容 |
| `inlineData` | 对象 | 否 | 内联媒体字节数据 |
| `fileData` | 对象 | 否 | 上传文件的URI引用 |
| `functionCall` | 对象 | 否 | 函数调用请求 |
| `functionResponse` | 对象 | 否 | 函数调用响应 |
| `executableCode` | 对象 | 否 | 可执行代码 |
| `codeExecutionResult` | 对象 | 否 | 代码执行结果 |
**InlineData 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ------------- |
| `mimeType` | 字符串 | 是 | 媒体的MIME类型 |
| `data` | 字符串 | 是 | base64编码的媒体数据 |
**FileData 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | --------- |
| `mimeType` | 字符串 | 是 | 文件的MIME类型 |
| `fileUri` | 字符串 | 是 | 文件的URI |
#### `tools` [#tools]
* 类型：数组
* 必需：否
模型可能用于生成下一个响应的工具列表。支持的工具包括函数和代码执行。
**Tool 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------------------- | -- | -- | --------- |
| `functionDeclarations` | 数组 | 否 | 可选的函数声明列表 |
| `codeExecution` | 对象 | 否 | 启用模型执行代码 |
**FunctionDeclaration 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --- | -- | ------------------ |
| `name` | 字符串 | 是 | 函数名称 |
| `description` | 字符串 | 否 | 函数功能描述 |
| `parameters` | 对象 | 否 | 函数参数，JSON Schema格式 |
**FunctionCall 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | -------- |
| `name` | 字符串 | 是 | 要调用的函数名称 |
| `args` | 对象 | 否 | 函数参数的键值对 |
**FunctionResponse 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | --------- |
| `name` | 字符串 | 是 | 调用的函数名称 |
| `response` | 对象 | 是 | 函数调用的响应数据 |
**ExecutableCode 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ------- |
| `language` | 枚举 | 是 | 代码的编程语言 |
| `code` | 字符串 | 是 | 要执行的代码 |
**CodeExecutionResult 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------- | --- | -- | --------- |
| `outcome` | 枚举 | 是 | 代码执行的结果状态 |
| `output` | 字符串 | 否 | 代码执行的输出内容 |
**CodeExecution 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| --- | --- | -- | -------------- |
| \{} | 空对象 | - | 启用代码执行功能的空配置对象 |
#### `toolConfig` [#toolconfig]
* 类型：对象
* 必需：否
请求中指定的任何工具的工具配置。
**ToolConfig 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ----------------------- | -- | -- | ------ |
| `functionCallingConfig` | 对象 | 否 | 函数调用配置 |
**FunctionCallingConfig 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------------------- | -- | -- | ---------- |
| `mode` | 枚举 | 否 | 指定函数调用的模式 |
| `allowedFunctionNames` | 数组 | 否 | 允许调用的函数名列表 |
**FunctionCallingMode 枚举值：**
* `MODE_UNSPECIFIED`: 默认模式，模型决定是否调用函数
* `AUTO`: 模型自动决定何时调用函数
* `ANY`: 模型必须调用函数
* `NONE`: 模型不能调用函数
#### `safetySettings` [#safetysettings]
* 类型：数组
* 必需：否
用于屏蔽不安全内容的 SafetySetting 实例列表。
**SafetySetting 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ----------- | -- | -- | ---- |
| `category` | 枚举 | 是 | 安全类别 |
| `threshold` | 枚举 | 是 | 屏蔽阈值 |
**HarmCategory 枚举值：**
* `HARM_CATEGORY_HARASSMENT`: 骚扰内容
* `HARM_CATEGORY_HATE_SPEECH`: 仇恨言论和内容
* `HARM_CATEGORY_SEXUALLY_EXPLICIT`: 露骨色情内容
* `HARM_CATEGORY_DANGEROUS_CONTENT`: 危险内容
* `HARM_CATEGORY_CIVIC_INTEGRITY`: 可能用于破坏公民诚信的内容
**HarmBlockThreshold 枚举值：**
* `BLOCK_LOW_AND_ABOVE`: 允许发布评分为 NEGLIGIBLE 的内容
* `BLOCK_MEDIUM_AND_ABOVE`: 允许发布评分为 NEGLIGIBLE 和 LOW 的内容
* `BLOCK_ONLY_HIGH`: 允许发布风险等级为 NEGLIGIBLE、LOW 和 MEDIUM 的内容
* `BLOCK_NONE`: 允许所有内容
* `OFF`: 关闭安全过滤器
**HarmBlockThreshold 完整枚举值：**
* `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: 未指定阈值
* `BLOCK_LOW_AND_ABOVE`: 屏蔽低概率及以上的有害内容，只允许 NEGLIGIBLE 级别的内容
* `BLOCK_MEDIUM_AND_ABOVE`: 屏蔽中等概率及以上的有害内容，允许 NEGLIGIBLE 和 LOW 级别的内容
* `BLOCK_ONLY_HIGH`: 只屏蔽高概率的有害内容，允许 NEGLIGIBLE、LOW 和 MEDIUM 级别的内容
* `BLOCK_NONE`: 不屏蔽任何内容，允许所有级别的内容
* `OFF`: 完全关闭安全过滤器
#### `systemInstruction` [#systeminstruction]
* 类型：对象（Content）
* 必需：否
开发者设置的系统指令。目前仅支持文本。
#### `generationConfig` [#generationconfig]
* 类型：对象
* 必需：否
模型生成和输出的配置选项。
**GenerationConfig 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------------------------- | --- | -- | ---------------------- |
| `stopSequences` | 数组 | 否 | 用于停止生成输出的字符序列集（最多5个） |
| `responseMimeType` | 字符串 | 否 | 生成的候选文本的MIME类型 |
| `responseSchema` | 对象 | 否 | 生成的候选文本的输出架构 |
| `responseModalities` | 数组 | 否 | 请求的响应模式 |
| `candidateCount` | 整数 | 否 | 要返回的生成的回答数量 |
| `maxOutputTokens` | 整数 | 否 | 候选回答中包含的令牌数量上限 |
| `temperature` | 数字 | 否 | 控制输出的随机性，范围\[0.0, 2.0] |
| `topP` | 数字 | 否 | 在抽样时要考虑的令牌的累计概率上限 |
| `topK` | 整数 | 否 | 抽样时要考虑的令牌数量上限 |
| `seed` | 整数 | 否 | 解码中使用的种子 |
| `presencePenalty` | 数字 | 否 | 存在性惩罚 |
| `frequencyPenalty` | 数字 | 否 | 频率惩罚 |
| `responseLogprobs` | 布尔值 | 否 | 是否在响应中导出logprobs结果 |
| `logprobs` | 整数 | 否 | 返回的顶部logprob的数量 |
| `enableEnhancedCivicAnswers` | 布尔值 | 否 | 启用增强型城市服务回答 |
| `speechConfig` | 对象 | 否 | 语音生成配置 |
| `thinkingConfig` | 对象 | 否 | 思考功能的配置 |
| `mediaResolution` | 枚举 | 否 | 指定的媒体分辨率 |
**支持的 MIME 类型：**
* `text/plain`: （默认）文本输出
* `application/json`: JSON响应
* `text/x.enum`: ENUM作为字符串响应
**Modality 枚举值：**
* `TEXT`: 指示模型应返回文本
* `IMAGE`: 表示模型应返回图片
* `AUDIO`: 指示模型应返回音频
**Schema 对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | ---- | -- | ---------------------------- |
| `type` | 枚举 | 是 | 数据类型 |
| `description` | 字符串 | 否 | 字段描述 |
| `enum` | 数组 | 否 | 枚举值列表（当type为string时） |
| `example` | 任意类型 | 否 | 示例值 |
| `nullable` | 布尔值 | 否 | 是否可为null |
| `format` | 字符串 | 否 | 字符串格式（如date、date-time等） |
| `items` | 对象 | 否 | 数组项的Schema（当type为array时） |
| `properties` | 对象 | 否 | 对象属性的Schema映射（当type为object时） |
| `required` | 数组 | 否 | 必需属性的名称列表 |
| `minimum` | 数字 | 否 | 数字的最小值 |
| `maximum` | 数字 | 否 | 数字的最大值 |
| `minItems` | 整数 | 否 | 数组的最小长度 |
| `maxItems` | 整数 | 否 | 数组的最大长度 |
| `minLength` | 整数 | 否 | 字符串的最小长度 |
| `maxLength` | 整数 | 否 | 字符串的最大长度 |
**Type 枚举值：**
* `TYPE_UNSPECIFIED`: 未指定类型
* `STRING`: 字符串类型
* `NUMBER`: 数字类型
* `INTEGER`: 整数类型
* `BOOLEAN`: 布尔类型
* `ARRAY`: 数组类型
* `OBJECT`: 对象类型
**支持的编程语言（ExecutableCode）：**
* `LANGUAGE_UNSPECIFIED`: 未指定语言
* `PYTHON`: Python编程语言
**代码执行结果枚举（Outcome）：**
* `OUTCOME_UNSPECIFIED`: 未指定结果
* `OUTCOME_OK`: 代码执行成功
* `OUTCOME_FAILED`: 代码执行失败
* `OUTCOME_DEADLINE_EXCEEDED`: 代码执行超时
#### `cachedContent` [#cachedcontent]
* 类型：字符串
* 必需：否
缓存的内容的名称，用于用作提供预测的上下文。格式：`cachedContents/{cachedContent}`
## 📥 响应 [#-响应]
### GenerateContentResponse [#generatecontentresponse]
支持多个候选回答的模型的回答。系统会针对提示以及每个候选项报告安全分级和内容过滤。
#### `candidates` [#candidates]
* 类型：数组
* 说明：模型的候选回答列表
**Candidate 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------------- | -- | -------------------- |
| `content` | 对象 | 模型返回的生成内容 |
| `finishReason` | 枚举 | 模型停止生成词元的原因 |
| `safetyRatings` | 数组 | 候选回答安全性的评分列表 |
| `citationMetadata` | 对象 | 模型生成的候选项的引用信息 |
| `tokenCount` | 整数 | 此候选项的令牌数 |
| `groundingAttributions` | 数组 | 为生成有依据的回答所参考的来源提供方信息 |
| `groundingMetadata` | 对象 | 候选对象的参考元数据 |
| `avgLogprobs` | 数字 | 候选项的平均对数概率得分 |
| `logprobsResult` | 对象 | 回答令牌和前置令牌的对数似然度得分 |
| `urlRetrievalMetadata` | 对象 | 与网址情境检索工具相关的元数据 |
| `urlContextMetadata` | 对象 | 与网址情境检索工具相关的元数据 |
| `index` | 整数 | 响应候选列表中候选项的索引 |
**FinishReason 枚举值：**
* `STOP`: 模型的自然停止点或提供的停止序列
* `MAX_TOKENS`: 已达到请求中指定的词元数量上限
* `SAFETY`: 出于安全考虑，系统已标记回答候选内容
* `RECITATION`: 由于背诵原因，回答候选内容被标记
* `LANGUAGE`: 回答候选内容因使用不受支持的语言而被标记
* `OTHER`: 原因未知
* `BLOCKLIST`: 由于内容包含禁止使用的字词，因此token生成操作已停止
* `PROHIBITED_CONTENT`: 由于可能包含禁止的内容，因此token生成操作已停止
* `SPII`: 由于内容可能包含敏感的个人身份信息，因此token生成操作已停止
* `MALFORMED_FUNCTION_CALL`: 模型生成的函数调用无效
* `IMAGE_SAFETY`: 由于生成的图片违反了安全规定，因此词元生成已停止
#### `promptFeedback` [#promptfeedback]
* 类型：对象
* 说明：与内容过滤器相关的提示反馈
**PromptFeedback 对象属性：**
| 属性 | 类型 | 描述 |
| --------------- | -- | -------- |
| `blockReason` | 枚举 | 屏蔽该提示的原因 |
| `safetyRatings` | 数组 | 问题安全性的评分 |
**BlockReason 枚举值：**
* `BLOCK_REASON_UNSPECIFIED`: 默认值，此值未使用
* `SAFETY`: 出于安全原因，系统屏蔽了提示
* `OTHER`: 提示因未知原因被屏蔽了
* `BLOCKLIST`: 系统屏蔽了此提示，因为其中包含术语屏蔽名单中包含的术语
* `PROHIBITED_CONTENT`: 系统屏蔽了此提示，因为其中包含禁止的内容
* `IMAGE_SAFETY`: 候选图片因生成不安全的内容而被屏蔽
#### `usageMetadata` [#usagemetadata]
* 类型：对象
* 说明：有关生成请求令牌用量的元数据
**UsageMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ---------------------------- | -- | ---------------- |
| `promptTokenCount` | 整数 | 提示中的词元数 |
| `cachedContentTokenCount` | 整数 | 提示的缓存部分中的词元数 |
| `candidatesTokenCount` | 整数 | 所有生成的候选回答中的词元总数 |
| `totalTokenCount` | 整数 | 生成请求的总令牌数 |
| `toolUsePromptTokenCount` | 整数 | 工具使用提示中的词元数量 |
| `thoughtsTokenCount` | 整数 | 思考模型的想法token数 |
| `promptTokensDetails` | 数组 | 在请求输入中处理的模态列表 |
| `candidatesTokensDetails` | 数组 | 响应中返回的模态列表 |
| `cacheTokensDetails` | 数组 | 请求输入中缓存内容的模态列表 |
| `toolUsePromptTokensDetails` | 数组 | 为工具使用请求输入处理的模态列表 |
#### `modelVersion` [#modelversion]
* 类型：字符串
* 说明：用于生成回答的模型版本
#### `responseId` [#responseid]
* 类型：字符串
* 说明：用于标识每个响应的ID
#### 完整响应示例 [#完整响应示例]
```json
{
"candidates": [
{
"content": {
"parts": [
{
"text": "你好！我是 Gemini，一个由 Google 开发的人工智能助手。我可以帮助您解答问题、提供信息、协助写作、代码编程等多种任务。请告诉我有什么可以为您效劳的！"
}
],
"role": "model"
},
"finishReason": "STOP",
"index": 0,
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_HARASSMENT",
"probability": "NEGLIGIBLE",
"blocked": false
},
{
"category": "HARM_CATEGORY_DANGEROUS_CONTENT",
"probability": "NEGLIGIBLE",
"blocked": false
}
],
"tokenCount": 47
}
],
"promptFeedback": {
"safetyRatings": [
{
"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
"probability": "NEGLIGIBLE"
},
{
"category": "HARM_CATEGORY_HATE_SPEECH",
"probability": "NEGLIGIBLE"
}
]
},
"usageMetadata": {
"promptTokenCount": 4,
"candidatesTokenCount": 47,
"totalTokenCount": 51,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 4
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 47
}
]
},
"modelVersion": "gemini-2.0-flash",
"responseId": "response-12345"
}
```
## 🔧 高级功能 [#-高级功能]
### 安全评级 [#安全评级]
**SafetyRating 对象属性：**
| 属性 | 类型 | 描述 |
| ------------- | --- | ------------- |
| `category` | 枚举 | 此评分的类别 |
| `probability` | 枚举 | 此内容的有害概率 |
| `blocked` | 布尔值 | 此内容是否因此分级而被屏蔽 |
**HarmProbability 枚举值：**
* `NEGLIGIBLE`: 内容不安全的概率可忽略不计
* `LOW`: 内容不安全的概率较低
* `MEDIUM`: 内容不安全的概率为中等
* `HIGH`: 内容不安全的概率较高
### 引用元数据 [#引用元数据]
**CitationMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------- | -- | --------- |
| `citationSources` | 数组 | 特定回复的来源引用 |
**CitationSource 对象属性：**
| 属性 | 类型 | 描述 |
| ------------ | --- | -------------------- |
| `startIndex` | 整数 | 归因于此来源的响应片段的开始索引 |
| `endIndex` | 整数 | 归因细分的结束索引（不含） |
| `uri` | 字符串 | 被归因为文本部分来源的URI |
| `license` | 字符串 | 被归因为片段来源的GitHub项目的许可 |
### 代码执行 [#代码执行]
当启用代码执行工具时，模型可以生成和执行代码来解决问题。
**代码执行示例响应：**
```json
{
"candidates": [
{
"content": {
"parts": [
{
"text": "我来计算斐波那契数列的第10项："
},
{
"executableCode": {
"language": "PYTHON",
"code": "def fibonacci(n):\n if n <= 1:\n return n\n else:\n return fibonacci(n-1) + fibonacci(n-2)\n\nresult = fibonacci(10)\nprint(f'第10项斐波那契数是: {result}')"
}
},
{
"codeExecutionResult": {
"outcome": "OK",
"output": "第10项斐波那契数是: 55"
}
},
{
"text": "所以斐波那契数列的第10项是55。"
}
],
"role": "model"
},
"finishReason": "STOP"
}
]
}
```
### 接地功能 (Grounding) [#接地功能-grounding]
**GroundingMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ------------------- | -- | ------------------- |
| `groundingChunks` | 数组 | 从指定的接地源检索到的支持参考文献列表 |
| `groundingSupports` | 数组 | 接地支持列表 |
| `webSearchQueries` | 数组 | 用于后续网页搜索的网页搜索查询 |
| `searchEntryPoint` | 对象 | 后续网页搜索的Google搜索条目 |
| `retrievalMetadata` | 对象 | 与基准流程中检索相关的元数据 |
**GroundingAttribution 对象属性：**
| 属性 | 类型 | 描述 |
| ---------- | -- | --------------- |
| `sourceId` | 对象 | 对此归因做出贡献的来源的标识符 |
| `content` | 对象 | 构成此归因的来源内容 |
**AttributionSourceId 对象属性：**
| 属性 | 类型 | 描述 |
| ------------------------ | -- | -------------------------------- |
| `groundingPassage` | 对象 | 内嵌段落的标识符 |
| `semanticRetrieverChunk` | 对象 | 通过Semantic Retriever提取的Chunk的标识符 |
**GroundingPassageId 对象属性：**
| 属性 | 类型 | 描述 |
| ----------- | --- | ----------------------------------------------------- |
| `passageId` | 字符串 | 与GenerateAnswerRequest的GroundingPassage.id匹配的段落的ID |
| `partIndex` | 整数 | GenerateAnswerRequest的GroundingPassage.content中的部分的索引 |
**SemanticRetrieverChunk 对象属性：**
| 属性 | 类型 | 描述 |
| -------- | --- | ----------------------------------------- |
| `source` | 字符串 | 与请求的SemanticRetrieverConfig.source匹配的来源名称 |
| `chunk` | 字符串 | 包含归因文本的Chunk的名称 |
**SearchEntryPoint 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------- | --- | -------------------------------- |
| `renderedContent` | 字符串 | 可嵌入网页或应用WebView中的Web内容代码段 |
| `sdkBlob` | 字符串 | 使用base64编码的JSON，表示搜索词和搜索URL元组的数组 |
**Segment 对象属性：**
| 属性 | 类型 | 描述 |
| ------------ | --- | ----------------------- |
| `partIndex` | 整数 | Part对象在其父级Content对象中的索引 |
| `startIndex` | 整数 | 给定part中的起始索引，以字节为单位 |
| `endIndex` | 整数 | 给定分块中的结束索引，以字节为单位 |
| `text` | 字符串 | 与响应中的片段对应的文本 |
**RetrievalMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------------------------- | -- | --------------------------------- |
| `googleSearchDynamicRetrievalScore` | 数字 | Google搜索中的信息有助于回答问题的概率得分，范围\[0,1] |
**GroundingChunk 对象属性：**
| 属性 | 类型 | 描述 |
| ----- | -- | --------- |
| `web` | 对象 | 来自网络的接地分块 |
**Web 对象属性：**
| 属性 | 类型 | 描述 |
| ------- | --- | -------- |
| `uri` | 字符串 | 分块的URI引用 |
| `title` | 字符串 | 数据块的标题 |
**GroundingSupport 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------------- | -- | ------------------- |
| `groundingChunkIndices` | 数组 | 索引列表，用于指定与版权主张相关的引文 |
| `confidenceScores` | 数组 | 支持参考文档的置信度分数，范围为0到1 |
| `segment` | 对象 | 此支持请求所属的内容片段 |
### 多模态处理 [#多模态处理]
Gemini API 支持处理多种模态的输入和输出：
**支持的输入模态：**
* `TEXT`: 纯文本
* `IMAGE`: 图片（JPEG、PNG、WebP、HEIC、HEIF）
* `AUDIO`: 音频（WAV、MP3、AIFF、AAC、OGG、FLAC）
* `VIDEO`: 视频（MP4、MPEG、MOV、AVI、FLV、MPG、WEBM、WMV、3GPP）
* `DOCUMENT`: 文档（PDF）
**ModalityTokenCount 对象属性：**
| 属性 | 类型 | 描述 |
| ------------ | -- | ---------- |
| `modality` | 枚举 | 与此令牌数关联的模态 |
| `tokenCount` | 整数 | 令牌数量 |
**MediaResolution 枚举值：**
* `MEDIA_RESOLUTION_LOW`: 低分辨率（64个令牌）
* `MEDIA_RESOLUTION_MEDIUM`: 中等分辨率（256个令牌）
* `MEDIA_RESOLUTION_HIGH`: 高分辨率（256个令牌进行缩放重新取景）
### 思考功能 [#思考功能]
**ThinkingConfig 对象属性：**
| 属性 | 类型 | 描述 |
| ----------------- | --- | ---------------- |
| `includeThoughts` | 布尔值 | 是否要在回答中包含思考内容 |
| `thinkingBudget` | 整数 | 模型应生成的想法token的数量 |
### 语音生成 [#语音生成]
**SpeechConfig 对象属性：**
| 属性 | 类型 | 描述 |
| ------------------------- | --- | ----------- |
| `voiceConfig` | 对象 | 单声音输出的配置 |
| `multiSpeakerVoiceConfig` | 对象 | 多音箱设置的配置 |
| `languageCode` | 字符串 | 用于语音合成的语言代码 |
**VoiceConfig 对象属性：**
| 属性 | 类型 | 描述 |
| --------------------- | -- | ------------ |
| `prebuiltVoiceConfig` | 对象 | 要使用的预构建语音的配置 |
**PrebuiltVoiceConfig 对象属性：**
| 属性 | 类型 | 描述 |
| ----------- | --- | ----------- |
| `voiceName` | 字符串 | 要使用的预设语音的名称 |
**MultiSpeakerVoiceConfig 对象属性：**
| 属性 | 类型 | 描述 |
| --------------------- | -- | ---------- |
| `speakerVoiceConfigs` | 数组 | 所有已启用的音箱语音 |
**SpeakerVoiceConfig 对象属性：**
| 属性 | 类型 | 描述 |
| ------------- | --- | --------- |
| `speaker` | 字符串 | 要使用的音箱的名称 |
| `voiceConfig` | 对象 | 要使用的语音的配置 |
**支持的语言代码：**
* `zh-CN`: 中文（简体）
* `en-US`: 英语（美国）
* `ja-JP`: 日语
* `ko-KR`: 韩语
* `fr-FR`: 法语
* `de-DE`: 德语
* `es-ES`: 西班牙语
* `pt-BR`: 葡萄牙语（巴西）
* `hi-IN`: 印地语
* `ar-XA`: 阿拉伯语
* `it-IT`: 意大利语
* `tr-TR`: 土耳其语
* `vi-VN`: 越南语
* `th-TH`: 泰语
* `ru-RU`: 俄语
* `pl-PL`: 波兰语
* `nl-NL`: 荷兰语
### Logprobs 结果 [#logprobs-结果]
**LogprobsResult 对象属性：**
| 属性 | 类型 | 描述 |
| ------------------ | -- | ---------------------------------- |
| `topCandidates` | 数组 | 长度等于解码步骤总数 |
| `chosenCandidates` | 数组 | 长度等于解码步骤总数，所选候选项不一定在topCandidates中 |
**TopCandidates 对象属性：**
| 属性 | 类型 | 描述 |
| ------------ | -- | ------------- |
| `candidates` | 数组 | 按对数概率降序排序的候选项 |
**Candidate (Logprobs) 对象属性：**
| 属性 | 类型 | 描述 |
| ---------------- | --- | ---------- |
| `token` | 字符串 | 候选项的令牌字符串值 |
| `tokenId` | 整数 | 候选项的令牌ID值 |
| `logProbability` | 数字 | 候选项的对数概率 |
### URL检索功能 [#url检索功能]
**UrlRetrievalMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ---------------------- | -- | -------- |
| `urlRetrievalContexts` | 数组 | 网址检索情境列表 |
**UrlRetrievalContext 对象属性：**
| 属性 | 类型 | 描述 |
| -------------- | --- | -------- |
| `retrievedUrl` | 字符串 | 工具检索到的网址 |
**UrlContextMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| ------------- | -- | ------- |
| `urlMetadata` | 数组 | 网址上下文列表 |
**UrlMetadata 对象属性：**
| 属性 | 类型 | 描述 |
| -------------------- | --- | -------- |
| `retrievedUrl` | 字符串 | 工具检索到的网址 |
| `urlRetrievalStatus` | 枚举 | 网址检索的状态 |
**UrlRetrievalStatus 枚举值：**
* `URL_RETRIEVAL_STATUS_SUCCESS`: 网址检索成功
* `URL_RETRIEVAL_STATUS_ERROR`: 由于出错，网址检索失败
### 完整安全类别 [#完整安全类别]
**HarmCategory 完整枚举值：**
* `HARM_CATEGORY_UNSPECIFIED`: 类别未指定
* `HARM_CATEGORY_DEROGATORY`: PaLM - 针对身份和/或受保护属性的负面或有害评论
* `HARM_CATEGORY_TOXICITY`: PaLM - 粗鲁、无礼或亵渎性的内容
* `HARM_CATEGORY_VIOLENCE`: PaLM - 描述描绘针对个人或团体的暴力行为的场景
* `HARM_CATEGORY_SEXUAL`: PaLM - 包含对性行为或其他淫秽内容的引用
* `HARM_CATEGORY_MEDICAL`: PaLM - 宣传未经核实的医疗建议
* `HARM_CATEGORY_DANGEROUS`: PaLM - 危险内容会宣扬、助长或鼓励有害行为
* `HARM_CATEGORY_HARASSMENT`: Gemini - 骚扰内容
* `HARM_CATEGORY_HATE_SPEECH`: Gemini - 仇恨言论和内容
* `HARM_CATEGORY_SEXUALLY_EXPLICIT`: Gemini - 露骨色情内容
* `HARM_CATEGORY_DANGEROUS_CONTENT`: Gemini - 危险内容
* `HARM_CATEGORY_CIVIC_INTEGRITY`: Gemini - 可能用于破坏公民诚信的内容
**HarmProbability 完整枚举值：**
* `HARM_PROBABILITY_UNSPECIFIED`: 概率未指定
* `NEGLIGIBLE`: 内容不安全的概率可忽略不计
* `LOW`: 内容不安全的概率较低
* `MEDIUM`: 内容不安全的概率为中等
* `HIGH`: 内容不安全的概率较高
**Modality 完整枚举值：**
* `MODALITY_UNSPECIFIED`: 未指定模态
* `TEXT`: 纯文本
* `IMAGE`: 图片
* `VIDEO`: 视频
* `AUDIO`: 音频
* `DOCUMENT`: 文档，例如PDF
**MediaResolution 完整枚举值：**
* `MEDIA_RESOLUTION_UNSPECIFIED`: 未设置媒体分辨率
* `MEDIA_RESOLUTION_LOW`: 媒体分辨率设为低（64个令牌）
* `MEDIA_RESOLUTION_MEDIUM`: 媒体分辨率设为中等（256个令牌）
* `MEDIA_RESOLUTION_HIGH`: 媒体分辨率设为高（使用256个令牌进行缩放重新取景）
**UrlRetrievalStatus 完整枚举值：**
* `URL_RETRIEVAL_STATUS_UNSPECIFIED`: 默认值，此值未使用
* `URL_RETRIEVAL_STATUS_SUCCESS`: 网址检索成功
* `URL_RETRIEVAL_STATUS_ERROR`: 由于出错，网址检索失败
## 🔍 错误处理 [#-错误处理]
### 常见错误码 [#常见错误码]
| 错误码 | 描述 |
| ----- | ----------- |
| `400` | 请求格式错误或参数无效 |
| `401` | API密钥无效或缺失 |
| `403` | 权限不足或配额限制 |
| `429` | 请求频率过高 |
| `500` | 服务器内部错误 |
### 详细错误码说明 [#详细错误码说明]
| 错误码 | 状态 | 描述 | 解决方案 |
| ----- | --------------------- | -------------- | -------------- |
| `400` | `INVALID_ARGUMENT` | 请求参数无效或格式错误 | 检查请求参数格式和必需字段 |
| `400` | `FAILED_PRECONDITION` | 请求的前置条件不满足 | 确保满足API调用的前置条件 |
| `401` | `UNAUTHENTICATED` | API密钥无效、缺失或已过期 | 检查API密钥的有效性和格式 |
| `403` | `PERMISSION_DENIED` | 权限不足或配额已用完 | 检查API密钥权限或升级配额 |
| `404` | `NOT_FOUND` | 指定的模型或资源不存在 | 验证模型名称和资源路径 |
| `413` | `PAYLOAD_TOO_LARGE` | 请求体太大 | 减少输入内容大小或分批处理 |
| `429` | `RESOURCE_EXHAUSTED` | 请求频率超限或配额不足 | 降低请求频率或等待配额重置 |
| `500` | `INTERNAL` | 服务器内部错误 | 重试请求，如持续出现联系支持 |
| `503` | `UNAVAILABLE` | 服务暂时不可用 | 等待一段时间后重试 |
| `504` | `DEADLINE_EXCEEDED` | 请求超时 | 减少输入大小或重试请求 |
### 错误响应示例 [#错误响应示例]
```json
{
"error": {
"code": 400,
"message": "Invalid argument: contents",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.BadRequest",
"fieldViolations": [
{
"field": "contents",
"description": "contents is required"
}
]
}
]
}
}
```
# Jina AI 重排序格式（Rerank） (/zh/api/jinaai-rerank)
[Jina AI Rerank](https://jina.ai/reranker)
在ZipFlow中，Jina AI的rerank格式被采用为标准格式。所有其他供应商（如Xinference、Cohere等）的rerank响应都会被格式化为Jina AI的格式，以提供统一的开发体验。
## 📝 简介 [#-简介]
Jina AI Rerank 是一个强大的文本重排序模型，可以根据查询对文档列表进行相关性排序。该模型支持多语言，可以处理不同语言的文本内容，并为每个文档分配相关性分数。
## 💡 请求示例 [#-请求示例]
### 基础重排序请求 ✅ [#基础重排序请求-]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "jina-reranker-v2-base-multilingual",
"query": "Organic skincare products for sensitive skin",
"top_n": 3,
"documents": [
"Organic skincare for sensitive skin with aloe vera and chamomile...",
"New makeup trends focus on bold colors and innovative techniques...",
"Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
]
}'
```
**响应示例:**
```json
{
"results": [
{
"document": {
"text": "Organic skincare for sensitive skin with aloe vera and chamomile..."
},
"index": 0,
"relevance_score": 0.8783142566680908
},
{
"document": {
"text": "Bio-Hautpflege für empfindliche Haut mit Aloe Vera und Kamille..."
},
"index": 2,
"relevance_score": 0.7624675869941711
}
],
"usage": {
"prompt_tokens": 815,
"completion_tokens": 0,
"total_tokens": 815
}
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/rerank
```
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### `model` [#model]
* 类型：字符串
* 必需：否
* 默认值：jina-reranker-v2-base-multilingual
* 说明：要使用的重排序模型
#### `query` [#query]
* 类型：字符串
* 必需：是
* 说明：用于对文档进行相关性排序的查询文本
#### `top_n` [#top_n]
* 类型：整数
* 必需：否
* 默认值：无限制
* 说明：返回排序后的前 N 个文档
#### `documents` [#documents]
* 类型：字符串数组
* 必需：是
* 说明：要进行重排序的文档列表
* 限制：每个文档的长度不应超过模型的最大token限制
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
#### `results` [#results]
* 类型：数组
* 说明：重排序后的文档列表
* 属性：
* `document`: 包含文档文本的对象
* `index`: 文档在原始列表中的索引
* `relevance_score`: 相关性分数(0-1之间)
#### `usage` [#usage]
* 类型：对象
* 说明：token 使用统计
* 属性：
* `prompt_tokens`: 提示使用的 token 数
* `completion_tokens`: 补全使用的 token 数
* `total_tokens`: 总 token 数
* `prompt_tokens_details`: 提示 token 详细信息
* `cached_tokens`: 缓存的 token 数
* `audio_tokens`: 音频 token 数
* `completion_tokens_details`: 补全 token 详细信息
* `reasoning_tokens`: 推理 token 数
* `audio_tokens`: 音频 token 数
* `accepted_prediction_tokens`: 接受的预测 token 数
* `rejected_prediction_tokens`: 拒绝的预测 token 数
### 错误响应 [#错误响应]
当请求出现问题时，API 将返回错误响应：
* `400 Bad Request`: 请求参数无效
* `401 Unauthorized`: API 密钥无效或未提供
* `429 Too Many Requests`: 请求频率超限
* `500 Internal Server Error`: 服务器内部错误
## 💡 最佳实践 [#-最佳实践]
### 查询优化建议 [#查询优化建议]
1. 使用清晰具体的查询文本
2. 避免过于宽泛或模糊的查询
3. 确保查询与文档使用相同的语言风格
### 文档处理建议 [#文档处理建议]
1. 保持文档长度适中，不要超过模型限制
2. 确保文档内容完整且有意义
3. 可以包含多语言文档，模型支持跨语言匹配
### 性能优化 [#性能优化]
1. 合理设置 top\_n 参数以减少不必要的计算
2. 对于大量文档，考虑分批处理
3. 可以缓存常用查询的结果
### 多语言支持 [#多语言支持]
该模型支持多种语言的文档重排序，包括但不限于：
* 英语
* 中文
* 德语
* 西班牙语
* 日语
* 法语
无需指定语言参数，模型会自动识别和处理不同语言的内容。
# 可灵AI (Kling)和即梦 (Jimeng)格式 (/zh/api/kling-jimeng)
调用视频生成接口生成视频，支持多种视频生成服务：
* **可灵AI (Kling)**: [API文档](https://app.klingai.com/cn/dev/document-api/apiReference/commonInfo)
* **即梦 (Jimeng)**: [API文档](https://www.volcengine.com/docs/85621/1538636)
## 生成视频 [#生成视频]
### API 端点 [#api-端点]
```
POST /v1/video/generations
```
### 请求头 [#请求头]
| 参数 | 类型 | 必填 | 描述 |
| ------------- | ------ | -- | ------------------------ |
| Authorization | string | 是 | 用户认证令牌 (Bearer: sk-xxxx) |
| Content-Type | string | 是 | application/json |
### 请求参数 [#请求参数]
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------- | -- | -------------------------------------------------------- |
| model | string | 是 | 模型/风格ID |
| prompt | string | 是 | 文本提示词 |
| duration | number | 否 | 视频时长（秒） |
| fps | integer | 否 | 视频帧率 |
| height | integer | 否 | 视频高度 |
| width | integer | 否 | 视频宽度 |
| image | string | 否 | 图片输入（URL/Base64） |
| metadata | object | 否 | 供应商特定/自定义参数（如 negative\_prompt, style, quality\_level 等） |
| n | integer | 否 | 生成视频数量 |
| response\_format | string | 否 | 响应格式 |
| seed | integer | 否 | 随机种子 |
| user | string | 否 | 用户标识符 |
### 请求示例 [#请求示例]
#### 可灵AI 示例 [#可灵ai-示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-v1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"duration": 5,
"metadata": {
"seed": 20231234,
"negative_prompt": "模糊",
"image_tail": "https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png"
}
}'
```
#### 即梦AI 示例 [#即梦ai-示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "一个穿着宇航服的宇航员在月球上行走",
"image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": [
"https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg"
],
"aspect_ratio": "16:9"
}
}'
```
#### Vidu 渠道示例 [#vidu-渠道示例]
```bash
curl https://api.zipflow.xyz/v1/video/generations \
--request POST \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"model": "viduq1",
"prompt": "一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级",
"size": "1920x1080",
"image": "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png",
"duration": 5,
"metadata": {
"duration": 5,
"seed": 0,
"resolution": "1080p",
"movement_amplitude": "auto",
"bgm": false,
"payload": "",
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
## 查询视频 [#查询视频]
根据任务ID查询视频生成任务的状态和结果
### API 端点 [#api-端点-1]
```
GET /v1/video/generations/{task_id}
```
### 路径参数 [#路径参数]
| 参数 | 类型 | 必填 | 描述 |
| -------- | ------ | -- | ---- |
| task\_id | string | 是 | 任务ID |
### 请求示例 [#请求示例-1]
```bash
curl 'https://api.zipflow.xyz/v1/video/generations/{task_id}'
```
### 响应格式 [#响应格式]
#### 200 - 成功响应 [#200---成功响应]
```json
{
"error": null,
"format": "mp4",
"metadata": {
"duration": 5,
"fps": 30,
"height": 512,
"seed": 20231234,
"width": 512
},
"status": "succeeded",
"task_id": "abcd1234efgh",
"url": "string"
}
```
#### 响应字段说明 [#响应字段说明]
| 字段 | 类型 | 描述 |
| -------- | ------ | ------------------------------------------------ |
| task\_id | string | 任务ID |
| status | string | 任务状态（processing: 处理中, succeeded: 成功, failed: 失败） |
| format | string | 视频格式 |
| url | string | 视频资源URL（成功时） |
| metadata | object | 结果元数据 |
| error | object | 错误信息（成功时为null） |
## 错误响应 [#错误响应]
### 400 - 请求参数错误 [#400---请求参数错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - 未授权 [#401---未授权]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - 无权限 [#403---无权限]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 500 - 服务器内部错误 [#500---服务器内部错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
# Midjourney 图像格式（Midjourney Proxy/Midjourney Proxy Plus） (/zh/api/midjourney-proxy-image)
该接口 **非Midjourney官方的接口**，而是基于作者 **novicezk** 的开源项目 [**midjourney-proxy**](https://github.com/novicezk/midjourney-proxy) 实现的midjourney代理接口。
该项目分为两个版本，ZipFlow 都已经适配：
* 开源版 [midjourney-proxy](https://github.com/novicezk/midjourney-proxy)
* 付费版 [midjourney-proxy-plus](https://github.com/litter-coder/midjourney-proxy-plus)
这里非常感谢作者的贡献，让我们可以方便使用midjourney的强大功能，如果有时间，请给作者一个Star，如果有能力，建议支持作者的付费版本，该版本支持更多功能。
| 功能类别 | 开源版 | 付费版 |
| ------------------- | --- | --- |
| **基础功能** | | |
| Imagine指令及相关动作 | ✓ | ✓ |
| 垫图支持 | ✓ | ✓ |
| Blend(图片混合) | ✓ | ✓ |
| Describe(图生文) | ✓ | ✓ |
| 任务实时进度 | ✓ | ✓ |
| 中文prompt翻译 | ✓ | ✓ |
| prompt敏感词检测 | ✓ | ✓ |
| user-token连接wss | ✓ | ✓ |
| 多账号配置 | ✓ | ✓ |
| **高级功能** | | |
| Shorten(prompt分析) | ✗ | ✓ |
| 焦点移动(Pan) | ✗ | ✓ |
| 图片变焦(Zoom) | ✗ | ✓ |
| 局部重绘(Vary Region) | ✗ | ✓ |
| 关联按钮动作和Remix模式 | ✗ | ✓ |
| 获取图片seed值 | ✗ | ✓ |
| **账号管理** | | |
| 账号池持久化 | ✗ | ✓ |
| 多种存储支持(Redis/MySQL) | ✗ | ✓ |
| 账号信息获取和设置 | ✗ | ✓ |
| 任务取消功能 | ✗ | ✓ |
| 内置管理后台 | ✗ | ✓ |
| **智能特性** | | |
| MJ V6.0支持 | ✗ | ✓ |
| 账号状态自动监控 | ✗ | ✓ |
| 模式自动切换 | ✗ | ✓ |
| niji・journey Bot支持 | ✗ | ✓ |
| InsightFace人脸服务 | ✗ | ✓ |
| **安全性能** | | |
| 动态配置支持 | ✗ | ✓ |
| token掉线问题修复 | ✗ | ✓ |
| 自动验证功能 | ✗ | ✓ |
| 违禁词自动申诉 | ✗ | ✓ |
## 📝 简介 [#-简介]
Midjourney是一个强大的图像生成和处理模型，可以根据自然语言描述创建、编辑和修改图像。通过提供不同的接口，可以实现各种图像生成和处理任务。
## 🔄 流程示意图 [#-流程示意图]
```mermaid
graph TD
A[开始] --> B{选择任务类型}
%% Imagine 流程
B -->|文生图| C[提交 Imagine 任务]
C --> D[获得初始图片]
D --> E{选择操作}
%% 基础操作分支
E -->|U1-U4| F[放大]
E -->|V1-V4| G[变体]
%% Blend 流程
B -->|图片混合| H[提交 Blend 任务]
H --> D
%% Describe 流程
B -->|图生文| I[提交 Describe 任务]
I --> J[获得图片描述]
%% Action & Modal 流程
F --> K[提交 Action]
G --> K
K -->|需要弹窗| L[提交 Modal]
K -->|直接执行| M[执行完成]
L --> M
%% Face Swap 流程
B -->|人脸替换| N[提交 Swap Face 任务]
N --> M
%% 查询相关
M --> O{后续操作}
O -->|查询进度| P[获取任务详情]
O -->|获取种子| Q[获取图片 Seed]
O -->|保存图片| R[上传至 Discord]
%% 样式定义
classDef process fill:#f9f,stroke:#333,stroke-width:2px
classDef decision fill:#bbf,stroke:#333,stroke-width:2px
classDef endpoint fill:#bfb,stroke:#333,stroke-width:2px
class A,M,J,R endpoint
class B,E,O decision
class C,D,F,G,H,I,K,L,N,P,Q process
```
### 流程说明 [#流程说明]
1. **初始任务**
* Imagine: 文本生成图片
* Blend: 多图混合
* Describe: 图片描述
* Swap Face: 人脸替换
2. **图片处理**
* U1-U4: 放大操作
* V1-V4: 变体生成
* Pan: 图片平移
* Zoom: 图片缩放
3. **特殊流程**
* Action + Modal: 需要弹窗确认的操作
* Action 直接执行: 不需要弹窗的操作
4. **任务管理**
* 获取任务详情
* 获取图片 Seed
* 上传至 Discord
## 💡 请求示例 [#-请求示例]
### 提交Imagine任务 ✅ [#提交imagine任务-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/imagine' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"prompt": "Cat",
"base64Array": [],
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**响应示例:**
```json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": 1320098173412546
}
```
### 提交Blend任务 ✅ [#提交blend任务-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/blend' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"base64Array": [
"data:image/png;base64,xxx1",
"data:image/png;base64,xxx2"
],
"dimensions": "SQUARE",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**响应示例:**
```json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": 1320098173412546
}
```
### 提交Describe任务 ✅ [#提交describe任务-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/describe' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"botType": "MID_JOURNEY",
"base64": "data:image/png;base64,xxx",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**响应示例:**
```json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": 1320098173412546
}
```
### 提交Modal ✅ [#提交modal-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/modal' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"maskBase64": "",
"prompt": "",
"taskId": "14001934816969359"
}'
```
**响应示例:**
```json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": 1320098173412546
}
```
### 提交swap\_face任务 ✅ [#提交swap_face任务-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/insight-face/swap' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"sourceBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RDnYdriP1wsS81kwU8OVs/R3xu8s6bX7+zYnOH8coSqpmRSBjqerjcBlr2OB/lbAf/2Q==",
"targetBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGBwgHBgkIBwgKCgkLDRYPDQwMDRsUFRAWIB0iIiAdHx8kKDQsJCYxJx8fLT0tMTU3Ojo6Iys/RD849k="
}'
```
**响应示例:**
```json
{
"code": 0,
"description": "string",
"result": "string"
}
```
### 执行Action动作 ✅ [#执行action动作-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/action' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"chooseSameChannel": true,
"customId": "MJ::JOB::upsample::1::82c51c9d-bc33-4c07-a471-36c3dcb1a6f0",
"taskId": "1728781324658687",
"accountFilter": {
"channelId": "",
"instanceId": "",
"modes": [],
"remark": "",
"remix": true,
"remixAutoConsidered": true
},
"notifyHook": "",
"state": ""
}'
```
**响应示例:**
```json
{
"code": 1,
"description": "提交成功",
"properties": {},
"result": 1320098173412546
}
```
### 上传文件到discord ✅ [#上传文件到discord-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/submit/upload-discord-images' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"base64Array": [],
"filter": {
"channelId": "",
"instanceId": "",
"remark": ""
}
}'
```
**响应示例:**
```json
{
"code": 0,
"description": "string",
"result": [
"string"
]
}
```
### 根据ID列表查询任务 ✅ [#根据id列表查询任务-]
```bash
curl --location --request POST 'https://api.zipflow.xyz/mj/task/list-by-condition' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"ids": []
}'
```
**响应示例:**
```json
[
{
"action": "IMAGINE",
"buttons": [
{
"customId": "string",
"emoji": "string",
"label": "string",
"style": 0,
"type": 0
}
],
"description": "string",
"failReason": "string",
"finishTime": 0,
"id": "string",
"imageUrl": "string",
"progress": "string",
"prompt": "string",
"promptEn": "string",
"properties": {},
"startTime": 0,
"state": "string",
"status": "NOT_START",
"submitTime": 0
}
]
```
### 指定ID获取任务 ✅ [#指定id获取任务-]
```bash
curl --location --request GET 'https://api.zipflow.xyz/mj/task/{id}/fetch' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json'
```
**响应示例:**
```json
{
"action": "IMAGINE",
"buttons": [
{
"customId": "string",
"emoji": "string",
"label": "string",
"style": 0,
"type": 0
}
],
"description": "string",
"failReason": "string",
"finishTime": 0,
"id": "string",
"imageUrl": "string",
"progress": "string",
"prompt": "string",
"promptEn": "string",
"properties": {},
"startTime": 0,
"state": "string",
"status": "NOT_START",
"submitTime": 0
}
```
### 获取任务图片的seed ✅ [#获取任务图片的seed-]
```bash
curl --location --request GET 'https://api.zipflow.xyz/mj/task/{id}/image-seed' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json'
```
**响应示例:**
```json
{
"code": 0,
"description": "string",
"result": "string"
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
#### 提交Imagine任务 [#提交imagine任务]
```
POST /mj/submit/imagine
```
根据文本提示创建图片。
#### 提交Blend任务 [#提交blend任务]
```
POST /mj/submit/blend
```
根据多个输入图片融合生成新图片。
#### 提交Describe任务 [#提交describe任务]
```
POST /mj/submit/describe
```
根据输入图片生成文字描述。
#### 提交Modal [#提交modal]
```
POST /mj/submit/modal
```
提交模态信息,用于调整图片生成细节。
#### 提交swap\_face任务 [#提交swap_face任务]
```
POST /mj/insight-face/swap
```
根据源图片和目标图片进行人脸交换。
#### 执行Action动作 [#执行action动作]
```
POST /mj/submit/action
```
对已生成的图片进行后续操作,如放大、调整等。
#### 上传文件到discord [#上传文件到discord]
```
POST /mj/submit/upload-discord-images
```
将图片上传到discord平台。
#### 根据ID列表查询任务 [#根据id列表查询任务]
```
POST /mj/task/list-by-condition
```
根据指定的任务ID列表查询任务详情。
#### 指定ID获取任务 [#指定id获取任务]
```
GET /mj/task/{id}/fetch
```
根据任务ID获取任务详情。
#### 获取任务图片的seed [#获取任务图片的seed]
```
GET /mj/task/{id}/image-seed
```
获取指定任务生成图片的seed值。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY$OPENAI_API_KEY
```
其中 `$OPENAI_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### 提交 Imagine 任务 [#提交-imagine-任务]
##### `botType` [#bottype]
* 类型：枚举字符串
* 必需：否
* 默认值：MID\_JOURNEY
* 可选值：
* `MID_JOURNEY`: Midjourney 模型
* `NIJI_JOURNEY`: Niji Journey 模型
* 说明：选择使用的 bot 类型
##### `prompt` [#prompt]
* 类型：字符串
* 必需：是
* 说明：图像生成的文本提示词
* 提示：
* 使用清晰具体的描述
* 可以包含艺术风格、构图等细节
* 支持英文和中文输入
##### `base64Array` [#base64array]
* 类型：字符串数组
* 必需：否
* 说明：垫图的 base64 编码数组
* 格式：每个元素应为完整的 base64 图片字符串，包含 MIME 类型前缀
##### `accountFilter` [#accountfilter]
* 类型：对象
* 必需：否
* 属性：
* `channelId`: 频道 ID
* `instanceId`: 账号实例 ID
* `modes`: 账号模式数组，可选值：RELAX、FAST、TURBO
* `remark`: 备注包含的内容
* `remix`: 账号是否支持 remix
* `remixAutoConsidered`: remix 自动提交设置
##### `notifyHook` [#notifyhook]
* 类型：字符串
* 必需：否
* 说明：任务完成后的回调地址，为空时使用全局 notifyHook
##### `state` [#state]
* 类型：字符串
* 必需：否
* 说明：自定义状态参数，可用于跟踪请求
#### 提交 Blend 任务 [#提交-blend-任务]
##### `base64Array` [#base64array-1]
* 类型：字符串数组
* 必需：是
* 说明：要混合的图片 base64 编码数组
* 格式：必须包含 2-5 张图片的 base64 字符串
##### `dimensions` [#dimensions]
* 类型：枚举字符串
* 必需：否
* 可选值：
* `PORTRAIT`: 2:3 比例
* `SQUARE`: 1:1 比例
* `LANDSCAPE`: 3:2 比例
* 说明：输出图片的宽高比设置
#### 提交 Describe 任务 [#提交-describe-任务]
##### `base64` [#base64]
* 类型：字符串
* 必需：是
* 说明：需要描述的图片的 base64 编码
* 格式：完整的 base64 字符串，包含 MIME 类型前缀
#### 提交 Modal 任务 [#提交-modal-任务]
##### `maskBase64` [#maskbase64]
* 类型：字符串
* 必需：否
* 说明：局部重绘的蒙版图片 base64 编码
##### `prompt` [#prompt-1]
* 类型：字符串
* 必需：否
* 说明：重绘区域的文本提示词
##### `taskId` [#taskid]
* 类型：字符串
* 必需：是
* 说明：原始任务的 ID
#### 提交 Swap Face 任务 [#提交-swap-face-任务]
##### `sourceBase64` [#sourcebase64]
* 类型：字符串
* 必需：是
* 说明：人脸源图片的 base64 编码
* 要求：图片必须包含清晰的人脸
##### `targetBase64` [#targetbase64]
* 类型：字符串
* 必需：是
* 说明：目标图片的 base64 编码
* 要求：图片必须包含要替换的人脸
#### 执行 Action 动作 [#执行-action-动作]
##### `chooseSameChannel` [#choosesamechannel]
* 类型：布尔值
* 必需：否
* 默认值：false
* 说明：是否选择同一频道下的账号
##### `customId` [#customid]
* 类型：字符串
* 必需：是
* 说明：动作标识符
* 格式：特定格式的字符串，如 "MJ::JOB::upsample::1::xxx"
##### `taskId` [#taskid-1]
* 类型：字符串
* 必需：是
* 说明：要执行动作的任务 ID
#### 上传文件到 Discord [#上传文件到-discord]
##### `base64Array` [#base64array-2]
* 类型：字符串数组
* 必需：是
* 说明：要上传的图片 base64 编码数组
##### `filter` [#filter]
* 类型：对象
* 必需：否
* 属性：
* `channelId`: 目标频道 ID
* `instanceId`: 账号实例 ID
* `remark`: 备注信息
#### 根据 ID 列表查询任务 [#根据-id-列表查询任务]
##### `ids` [#ids]
* 类型：字符串数组
* 必需：是
* 说明：要查询的任务 ID 列表
### 通用响应格式 [#通用响应格式]
所有接口都返回相似的响应结构：
##### `code` [#code]
* 类型：整数
* 说明：状态码
| 状态码 | 说明 |
| --- | ----- |
| 1 | 提交成功 |
| 22 | 任务排队中 |
| 21 | 参数错误 |
| 23 | 系统错误 |
| 24 | 账号不可用 |
| 25 | 余额不足 |
##### `description` [#description]
* 类型：字符串
* 说明：响应描述信息
##### `properties` [#properties]
* 类型：对象
* 说明：扩展属性
##### `result` [#result]
* 类型：字符串或数组
* 说明：返回结果，可能是任务 ID 或其他数据
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
#### `action` [#action]
* 类型：枚举字符串
* 说明：任务类型
| 字符串值 | 说明 |
| ----------- | ----- |
| `IMAGINE` | 创建图片 |
| `UPSCALE` | 放大图片 |
| `VARIATION` | 变体生成 |
| `ZOOM` | 缩放图片 |
| `PAN` | 平移图片 |
| `DESCRIBE` | 图片描述 |
| `BLEND` | 图片混合 |
| `SHORTEN` | 缩短提示词 |
| `SWAP_FACE` | 人脸替换 |
#### `buttons` [#buttons]
* 类型：对象数组
* 说明：可执行的操作按钮
| 数组包含属性 | 说明 |
| ---------- | ---------------------- |
| `customId` | 动作标识 |
| `emoji` | 按钮图标 |
| `label` | 按钮文本 |
| `style` | 样式(2=Primary, 3=Green) |
| `type` | 系统内部使用的类型 |
#### `description` [#description-1]
* 类型：字符串
* 说明：任务描述信息
#### `failReason` [#failreason]
* 类型：字符串
* 说明：任务失败原因
#### `finishTime` [#finishtime]
* 类型：整数
* 说明：任务完成时间戳
#### `id` [#id]
* 类型：字符串
* 说明：任务唯一标识符
#### `imageUrl` [#imageurl]
* 类型：字符串
* 说明：生成图片的URL
#### `progress` [#progress]
* 类型：字符串
* 说明：任务进度信息
#### `prompt` [#prompt-2]
* 类型：字符串
* 说明：原始提示词
#### `promptEn` [#prompten]
* 类型：字符串
* 说明：英文提示词
#### `status` [#status]
* 类型：枚举字符串
* 说明：任务状态
| 字符串值 | 说明 |
| ------------- | ----- |
| `NOT_START` | 未开始 |
| `SUBMITTED` | 已提交 |
| `MODAL` | 模态操作中 |
| `IN_PROGRESS` | 进行中 |
| `FAILURE` | 失败 |
| `SUCCESS` | 成功 |
| `CANCEL` | 已取消 |
#### `submitTime` [#submittime]
* 类型：整数
* 说明：任务提交时间戳
#### `startTime` [#starttime]
* 类型：整数
* 说明：任务开始执行时间戳
### 错误响应 [#错误响应]
当请求出现问题时，API 将返回错误响应：
#### HTTP 状态码 [#http-状态码]
* `400 Bad Request`: 请求参数无效
* `401 Unauthorized`: API 密钥无效或未提供
* `403 Forbidden`: 权限不足
* `404 Not Found`: 资源不存在
* `429 Too Many Requests`: 请求频率超限
* `500 Internal Server Error`: 服务器内部错误
#### 错误响应格式 [#错误响应格式]
```json
{
"code": <错误码>,
"description": "错误描述信息",
"result": null
}
```
## 💡 最佳实践 [#-最佳实践]
### Prompt 编写建议 [#prompt-编写建议]
1. 使用清晰简洁的语言描述期望的图像内容
2. 可以参考Midjourney支持的各种参数来控制图片风格
3. 适当使用否定描述以排除不需要的元素
4. 可以通过图片URL作为参考来指导生成
### 图片生成流程 [#图片生成流程]
1. 提交Imagine任务,获得初步图片
2. 必要时通过Blend、Modal等任务进一步优化
3. 执行Action动作进行图片微调
4. 将满意的结果图片上传保存
### 图片格式要求 [#图片格式要求]
1. 支持的图片格式：
* JPEG/JPG
* PNG
* GIF (静态)
* WEBP
2. 图片大小限制：
* 文件大小：最大 4MB
* 分辨率：建议 1024x1024 或更高
* 宽高比：支持 1:1、2:3、3:2
### 性能优化建议 [#性能优化建议]
1. Base64 编码：
* 使用标准 Base64 编码格式
* 包含正确的 MIME 类型前缀
* 压缩图片以减少数据传输
2. 任务处理：
* 使用 webhook 接收任务完成通知
* 合理设置重试策略
* 建议使用异步处理方式
### 错误处理 [#错误处理]
* 实现请求重试机制
* 添加错误日志记录
* 设置合理的超时时间
# OpenAI 音频格式 (/zh/api/openai-audio)
[OpenAI Audio](https://platform.openai.com/docs/api-reference/audio)
## 📝 简介 [#-简介]
OpenAI 音频 API 提供了三个主要功能:
1. 文本转语音(TTS) - 将文本转换为自然的语音
2. 语音转文本(STT) - 将音频转录为文本
3. 音频翻译 - 将非英语音频翻译成英语文本
## 💡 请求示例 [#-请求示例]
### 文本转语音 ✅ [#文本转语音-]
```bash
curl https://api.zipflow.xyz/v1/audio/speech \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tts-1",
"input": "你好,世界!",
"voice": "alloy"
}' \
--output speech.mp3
```
### 语音转文本 ✅ [#语音转文本-]
```bash
curl https://api.zipflow.xyz/v1/audio/transcriptions \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/audio.mp3" \
-F model="whisper-1"
```
**响应示例:**
```json
{
"text": "你好,世界!"
}
```
### 音频翻译 ✅ [#音频翻译-]
```bash
curl https://api.zipflow.xyz/v1/audio/translations \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F file="@/path/to/file/chinese.mp3" \
-F model="whisper-1"
```
**响应示例:**
```json
{
"text": "Hello, world!"
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
#### 文本转语音 [#文本转语音]
```
POST /v1/audio/speech
```
将文本转换为语音。
#### 语音转文本 [#语音转文本]
```
POST /v1/audio/transcriptions
```
将音频转录为输入语言的文本。
#### 音频翻译 [#音频翻译]
```
POST /v1/audio/translations
```
将音频翻译为英语文本。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### 文本转语音 [#文本转语音-1]
##### `model` [#model]
* 类型：字符串
* 必需：是
* 可选值：tts-1, tts-1-hd
* 说明：要使用的 TTS 模型
##### `input` [#input]
* 类型：字符串
* 必需：是
* 最大长度：4096 字符
* 说明：要转换为语音的文本
##### `voice` [#voice]
* 类型：字符串
* 必需：是
* 可选值：alloy, echo, fable, onyx, nova, shimmer
* 说明：生成语音时使用的声音
##### `response_format` [#response_format]
* 类型：字符串
* 必需：否
* 默认值：mp3
* 可选值：mp3, opus, aac, flac, wav, pcm
* 说明：音频输出格式
##### `speed` [#speed]
* 类型：数字
* 必需：否
* 默认值：1.0
* 范围：0.25 - 4.0
* 说明：生成语音的速度
#### 语音转文本 [#语音转文本-1]
##### `file` [#file]
* 类型：文件
* 必需：是
* 支持格式：flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* 说明：要转录的音频文件
##### `model` [#model-1]
* 类型：字符串
* 必需：是
* 当前仅支持：whisper-1
* 说明：要使用的模型 ID
##### `language` [#language]
* 类型：字符串
* 必需：否
* 格式：ISO-639-1 (如 "en")
* 说明：音频的语言,提供可提高准确性
##### `prompt` [#prompt]
* 类型：字符串
* 必需：否
* 说明：用于指导模型风格或继续前一段音频的文本
##### `response_format` [#response_format-1]
* 类型：字符串
* 必需：否
* 默认值：json
* 可选值：json, text, srt, verbose\_json, vtt
* 说明：输出格式
##### `temperature` [#temperature]
* 类型：数字
* 必需：否
* 默认值：0
* 范围：0 - 1
* 说明：采样温度,较高的值使输出更随机
##### `timestamp_granularities` [#timestamp_granularities]
* 类型：数组
* 必需：否
* 默认值：segment
* 可选值：word, segment
* 说明：转录的时间戳粒度
#### 音频翻译 [#音频翻译-1]
##### `file` [#file-1]
* 类型：文件
* 必需：是
* 支持格式：flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm
* 说明：要翻译的音频文件
##### `model` [#model-2]
* 类型：字符串
* 必需：是
* 当前仅支持：whisper-1
* 说明：要使用的模型 ID
##### `prompt` [#prompt-1]
* 类型：字符串
* 必需：否
* 说明：用于指导模型风格的英文文本
##### `response_format` [#response_format-2]
* 类型：字符串
* 必需：否
* 默认值：json
* 可选值：json, text, srt, verbose\_json, vtt
* 说明：输出格式
##### `temperature` [#temperature-1]
* 类型：数字
* 必需：否
* 默认值：0
* 范围：0 - 1
* 说明：采样温度,较高的值使输出更随机
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
#### 文本转语音 [#文本转语音-2]
返回二进制音频文件内容。
#### 语音转文本 [#语音转文本-2]
##### 基础 JSON 格式 [#基础-json-格式]
```json
{
"text": "转录的文本内容"
}
```
##### 详细 JSON 格式 [#详细-json-格式]
```json
{
"task": "transcribe",
"language": "english",
"duration": 8.47,
"text": "完整的转录文本",
"segments": [
{
"id": 0,
"seek": 0,
"start": 0.0,
"end": 3.32,
"text": "分段的转录文本",
"tokens": [50364, 440, 7534],
"temperature": 0.0,
"avg_logprob": -0.286,
"compression_ratio": 1.236,
"no_speech_prob": 0.009
}
]
}
```
#### 音频翻译 [#音频翻译-2]
```json
{
"text": "翻译后的英文文本"
}
```
### 错误响应 [#错误响应]
当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。
#### 常见错误状态码 [#常见错误状态码]
* `400 Bad Request`: 请求参数无效
* `401 Unauthorized`: API 密钥无效或未提供
* `429 Too Many Requests`: 超出 API 调用限制
* `500 Internal Server Error`: 服务器内部错误
错误响应示例:
```json
{
"error": {
"message": "文件格式不支持",
"type": "invalid_request_error",
"param": "file",
"code": "invalid_file_format"
}
}
```
# OpenAI 对话格式（Chat Completions） (/zh/api/openai-chat)
[OpenAI Chat](https://platform.openai.com/docs/api-reference/chat)
## 📝 简介 [#-简介]
给定一组包含对话的消息列表，模型将返回一个响应。相关指南可参阅OpenAI官网：[Chat Completions](https://platform.openai.com/docs/guides/chat)
## 💡 请求示例 [#-请求示例]
### 基础文本对话 ✅ [#基础文本对话-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "你是一个有帮助的助手。"
},
{
"role": "user",
"content": "你好！"
}
]
}'
```
**响应示例:**
```json
{
"id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
"object": "chat.completion",
"created": 1741569952,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！我能为你提供什么帮助？",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 19,
"completion_tokens": 10,
"total_tokens": 29,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default"
}
```
### 图像分析对话 ✅ [#图像分析对话-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "这张图片里有什么？"
},
{
"type": "image_url",
"image_url": {
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
}
]
}
],
"max_tokens": 300
}'
```
**响应示例:**
```json
{
"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
"object": "chat.completion",
"created": 1741570283,
"model": "gpt-4.1-2025-04-14",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "图片展示了一条穿过茂密绿色草地或草甸的木制栈道。天空湛蓝，点缀着几朵散落的云彩，给整个场景营造出宁静祥和的氛围。背景中可以看到树木和灌木丛。",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1117,
"completion_tokens": 46,
"total_tokens": 1163,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default",
"system_fingerprint": "fp_fc9f1d7035"
}
```
### 流式响应 ✅ [#流式响应-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "developer",
"content": "你是一个有帮助的助手。"
},
{
"role": "user",
"content": "你好！"
}
],
"stream": true
}'
```
**流式响应示例:**
```jsonl
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"你好"},"logprobs":null,"finish_reason":null}]}
// ... 更多数据块 ...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}
```
### 函数调用 ✅ [#函数调用-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": "波士顿今天的天气怎么样？"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
}
}
}
],
"tool_choice": "auto"
}'
```
**响应示例:**
```json
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1699896916,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_current_weather",
"arguments": "{\n\"location\": \"Boston, MA\"\n}"
}
}
]
},
"logprobs": null,
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 82,
"completion_tokens": 17,
"total_tokens": 99,
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
}
}
```
### Logprobs 请求 ✅ [#logprobs-请求-]
```bash
curl https://api.zipflow.xyz/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"messages": [
{
"role": "user",
"content": "你好！"
}
],
"logprobs": true,
"top_logprobs": 2
}'
```
**响应示例:**
```json
{
"id": "chatcmpl-123",
"object": "chat.completion",
"created": 1702685778,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！我能为你提供什么帮助？"
},
"logprobs": {
"content": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111],
"top_logprobs": [
{
"token": "Hello",
"logprob": -0.31725305,
"bytes": [72, 101, 108, 108, 111]
},
{
"token": "Hi",
"logprob": -1.3190403,
"bytes": [72, 105]
}
]
},
{
"token": "!",
"logprob": -0.02380986,
"bytes": [
33
],
"top_logprobs": [
{
"token": "!",
"logprob": -0.02380986,
"bytes": [33]
},
{
"token": " there",
"logprob": -3.787621,
"bytes": [32, 116, 104, 101, 114, 101]
}
]
},
{
"token": " How",
"logprob": -0.000054669687,
"bytes": [32, 72, 111, 119],
"top_logprobs": [
{
"token": " How",
"logprob": -0.000054669687,
"bytes": [32, 72, 111, 119]
},
{
"token": "<|end|>",
"logprob": -10.953937,
"bytes": null
}
]
},
{
"token": " can",
"logprob": -0.015801601,
"bytes": [32, 99, 97, 110],
"top_logprobs": [
{
"token": " can",
"logprob": -0.015801601,
"bytes": [32, 99, 97, 110]
},
{
"token": " may",
"logprob": -4.161023,
"bytes": [32, 109, 97, 121]
}
]
},
{
"token": " I",
"logprob": -3.7697225e-6,
"bytes": [
32,
73
],
"top_logprobs": [
{
"token": " I",
"logprob": -3.7697225e-6,
"bytes": [32, 73]
},
{
"token": " assist",
"logprob": -13.596657,
"bytes": [32, 97, 115, 115, 105, 115, 116]
}
]
},
{
"token": " assist",
"logprob": -0.04571125,
"bytes": [32, 97, 115, 115, 105, 115, 116],
"top_logprobs": [
{
"token": " assist",
"logprob": -0.04571125,
"bytes": [32, 97, 115, 115, 105, 115, 116]
},
{
"token": " help",
"logprob": -3.1089056,
"bytes": [32, 104, 101, 108, 112]
}
]
},
{
"token": " you",
"logprob": -5.4385737e-6,
"bytes": [32, 121, 111, 117],
"top_logprobs": [
{
"token": " you",
"logprob": -5.4385737e-6,
"bytes": [32, 121, 111, 117]
},
{
"token": " today",
"logprob": -12.807695,
"bytes": [32, 116, 111, 100, 97, 121]
}
]
},
{
"token": " today",
"logprob": -0.0040071653,
"bytes": [32, 116, 111, 100, 97, 121],
"top_logprobs": [
{
"token": " today",
"logprob": -0.0040071653,
"bytes": [32, 116, 111, 100, 97, 121]
},
{
"token": "?",
"logprob": -5.5247097,
"bytes": [63]
}
]
},
{
"token": "?",
"logprob": -0.0008108172,
"bytes": [63],
"top_logprobs": [
{
"token": "?",
"logprob": -0.0008108172,
"bytes": [63]
},
{
"token": "?\n",
"logprob": -7.184561,
"bytes": [63, 10]
}
]
}
]
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 9,
"total_tokens": 18,
"completion_tokens_details": {
"reasoning_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"system_fingerprint": null
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/chat/completions
```
创建给定聊天对话的模型响应。更多详情请参阅文本生成、视觉和音频指南。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。您可以在 ZipFlow 控制台的 API 密钥页面中找到或生成 API 密钥。
### 请求体参数 [#请求体参数]
#### `messages` [#messages]
* 类型：数组
* 必需：是
到目前为止包含对话的消息列表。根据使用的模型，支持不同的消息类型（形式），如文本、图像和音频。
| 消息类型 | 描述 |
| --------------------- | ------------------------------------------------------------ |
| **Developer message** | 开发者提供的指令，模型应遵循这些指令，无论用户发送什么消息。在 o1 模型及更新版本中，开发者消息取代了之前的系统消息。 |
| **System message** | 开发者提供的指令，模型应遵循这些指令，无论用户发送什么消息。在 o1 模型及更新版本中，请使用开发者消息代替。 |
| **User message** | 由终端用户发送的消息，包含提示或额外的上下文信息。 |
| **Assistant message** | 模型响应用户消息发送的消息。 |
| **Tool message** | 工具消息的内容。 |
| **Function message** | 已弃用。 |
**Developer message 属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------- | ------ | -- | ----------------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `developer`。 |
| `content` | 字符串或数组 | 是 | 开发者消息的内容。可以是文本内容（字符串）或内容部分数组。 |
| `name` | 字符串 | 否 | 参与者的可选名称。为模型提供信息以区分相同角色的参与者。 |
**System message 属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------- | ------ | -- | ---------------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `system`。 |
| `content` | 字符串或数组 | 是 | 系统消息的内容。可以是文本内容（字符串）或内容部分数组。 |
| `name` | 字符串 | 否 | 参与者的可选名称。为模型提供信息以区分相同角色的参与者。 |
**User message 属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------- | ------ | -- | ---------------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `user`。 |
| `content` | 字符串或数组 | 是 | 用户消息的内容。可以是文本内容（字符串）或内容部分数组。 |
| `name` | 字符串 | 否 | 参与者的可选名称。为模型提供信息以区分相同角色的参与者。 |
**内容部分类型：**
| 内容部分类型 | 描述 | 可用于 |
| ---------- | ------------ | ------ |
| **文本内容部分** | 文本输入。 | 所有消息类型 |
| **图像内容部分** | 图像输入。 | 用户消息 |
| **音频内容部分** | 音频输入。 | 用户消息 |
| **文件内容部分** | 文件输入，用于文本生成。 | 用户消息 |
| **拒绝内容部分** | 模型生成的拒绝消息。 | 助手消息 |
**文本内容部分属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | -------- |
| `text` | 字符串 | 是 | 文本内容。 |
| `type` | 字符串 | 是 | 内容部分的类型。 |
**图像内容部分属性：**
| 属性 | 类型 | 必需 | 描述 |
| ----------- | --- | -- | ---------------------- |
| `image_url` | 对象 | 是 | 包含图像URL或base64编码的图像数据。 |
| `type` | 字符串 | 是 | 内容部分的类型。 |
**图像URL对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | --------------------- |
| `url` | 字符串 | 是 | 图像的URL或base64编码的图像数据。 |
| `detail` | 字符串 | 否 | 指定图像的详细级别。默认为 `auto`。 |
**音频内容部分属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --- | -- | -------------------------- |
| `input_audio` | 对象 | 是 | 包含音频数据的对象。 |
| `type` | 字符串 | 是 | 内容部分的类型。始终为 `input_audio`。 |
**音频输入对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | ----------------------------- |
| `data` | 字符串 | 是 | base64编码的音频数据。 |
| `format` | 字符串 | 是 | 编码音频数据的格式。当前支持 "wav" 和 "mp3"。 |
**文件内容部分属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | ------------------- |
| `file` | 对象 | 是 | 包含文件数据的对象。 |
| `type` | 字符串 | 是 | 内容部分的类型。始终为 `file`。 |
**文件对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ----------- | --- | -- | ------------------------------ |
| `file_data` | 字符串 | 否 | base64编码的文件数据，用于将文件作为字符串传递给模型。 |
| `file_id` | 字符串 | 否 | 已上传文件的ID，用作输入。 |
| `filename` | 字符串 | 否 | 文件名，用于将文件作为字符串传递给模型。 |
**Assistant message 属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------------- | -------- | -- | --------------------------------------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `assistant`。 |
| `content` | 字符串或数组 | 否 | 助手消息的内容。除非指定了 `tool_calls` 或 `function_call`，否则为必需。 |
| `name` | 字符串 | 否 | 参与者的可选名称。为模型提供信息以区分相同角色的参与者。 |
| `audio` | 对象或null | 否 | 关于模型先前音频响应的数据。 |
| `function_call` | 对象或null | 否 | 已弃用，由 `tool_calls` 替代。应调用的函数的名称和参数，由模型生成。 |
| `tool_calls` | 数组 | 否 | 模型生成的工具调用，如函数调用。 |
| `refusal` | 字符串或null | 否 | 助手的拒绝消息。 |
**Tool message 属性：**
| 属性 | 类型 | 必需 | 描述 |
| -------------- | ------ | -- | ------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `tool`。 |
| `content` | 字符串或数组 | 是 | 工具消息的内容。 |
| `tool_call_id` | 字符串 | 是 | 此消息响应的工具调用。 |
**Function message 属性：（已弃用）**
| 属性 | 类型 | 必需 | 描述 |
| --------- | -------- | -- | ----------------------- |
| `role` | 字符串 | 是 | 消息作者的角色，此处为 `function`。 |
| `content` | 字符串或null | 是 | 函数消息的内容。 |
| `name` | 字符串 | 是 | 要调用的函数的名称。 |
#### `model` [#model]
* 类型：字符串
* 必需：是
要使用的模型 ID。有关哪些模型适用于 Chat API 的详细信息，请参阅模型端点兼容性表。
#### `store` [#store]
* 类型：布尔值或 null
* 必需：否
* 默认值：false
是否存储此聊天补全请求的输出以用于我们的模型蒸馏或评估产品。
#### `reasoning_effort` [#reasoning_effort]
* 类型：字符串或 null
* 必需：否
* 默认值：medium
* 仅适用于 o系列 的模型
约束推理模型的推理工作。当前支持的值为 `low`、`medium` 和 `high`。减少推理工作可以加快响应速度并减少响应中用于推理的标记数。
#### `metadata` [#metadata]
* 类型：map
* 必需：否
可以附加到对象的16个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。
键是最大长度为64个字符的字符串。值是最大长度为512个字符的字符串。
#### `modalities` [#modalities]
* 类型：数组或 null
* 必需：否
您希望模型为此请求生成的输出类型。大多数模型都能生成文本,这是默认设置:
\["text"]
该模型还可以用于生成音频。要请求此模型同时生成文本和音频响应,您可以使用:
\["text", "audio"]
#### `prediction` [#prediction]
* 类型：对象
* 必需：否
预测输出的配置,当提前知道模型响应的大部分内容时,可以大大提高响应时间。这在您只对文件进行微小更改时最常见。
**可能的类型：**
| 类型 | 描述 |
| -------- | -------------------------------- |
| **静态内容** | 静态预测输出内容，例如正在重新生成的具有微小更改的文本文件内容。 |
**静态内容属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------- | ------ | -- | ------------------------------------------- |
| `content` | 字符串或数组 | 是 | 生成模型响应时应匹配的内容。如果生成的标记与此内容匹配，则整个模型响应可以更快地返回。 |
| `type` | 字符串 | 是 | 要提供的预测内容类型。当前类型始终为 `content`。 |
**内容可能的类型：**
1. **文本内容（字符串）** - 用于预测输出的内容。这通常是您正在重新生成的文件的文本，只有微小更改。
2. **内容部分数组（数组）** - 具有定义类型的内容部分数组。支持的选项因用于生成响应的模型而异。可以包含文本输入。
**内容部分数组属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | -------- |
| `text` | 字符串 | 是 | 文本内容。 |
| `type` | 字符串 | 是 | 内容部分的类型。 |
#### `audio` [#audio]
* 类型：对象或 null
* 必需：否
音频输出的参数。当使用 `modalities: ["audio"]` 请求音频输出时需要。
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | ----------------------------------------------------------------------------- |
| `format` | 字符串 | 是 | 指定输出音频格式。必须是以下之一：wav、mp3、flac、opus 或 pcm16。 |
| `voice` | 字符串 | 是 | 模型用于响应的声音。支持的声音包括：alloy、ash、ballad、coral、echo、fable、nova、onyx、sage 和 shimmer。 |
#### `temperature` [#temperature]
* 类型：数字或 null
* 必需：否
* 默认值：1
要使用的采样温度，介于 0 和 2 之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议更改此值或 `top_p`，但不要同时更改。
#### `top_p` [#top_p]
* 类型：数字或 null
* 必需：否
* 默认值：1
一种替代采样温度的方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。
我们通常建议更改此值或 `temperature`，但不要同时更改。
#### `n` [#n]
* 类型：整数或 null
* 必需：否
* 默认值：1
为每个输入消息生成多少个聊天补全选择。请注意，您将根据所有选择生成的标记数量收费。保持 `n` 为 1 可最大限度地降低成本。
#### `stop` [#stop]
* 类型：字符串/数组/null
* 必需：否
* 默认值：null
* 不支持最新的推理模型和 .o3、o4-mini
API 将停止生成更多标记的最多 4 个序列。返回的文本不会包含停止序列。
#### `max_tokens` [#max_tokens]
* 类型：整数或 null
* 必需：否
聊天补全中可以生成的最大标记数。此值可用于控制通过 API 生成的文本成本。
该值现已弃用，取而代之的是 `max_completion_tokens`，并且与 `o1` 系列模型不兼容。
#### `max_completion_tokens` [#max_completion_tokens]
* 类型：整数或 null
* 必需：否
补全中可以生成的标记数的上限，包括可见输出标记和推理标记。
#### `presence_penalty` [#presence_penalty]
* 类型：数字或 null
* 必需：否
* 默认值：0
介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中出现的情况来惩罚它们，从而增加模型讨论新主题的可能性。
#### `frequency_penalty` [#frequency_penalty]
* 类型：数字或 null
* 必需：否
* 默认值：0
介于 -2.0 和 2.0 之间的数字。正值根据新标记到目前为止在文本中的现有频率来惩罚它们，从而降低模型逐字重复同一行的可能性。
#### `logit_bias` [#logit_bias]
* 类型：map
* 必需：否
* 默认值：null
修改指定标记出现在补全中的可能性。
接受一个 JSON 对象，该对象将标记（由分词器中的标记 ID 指定）映射到从 -100 到 100 的关联偏差值。在数学上，偏差被添加到模型在采样之前生成的对数中。确切的效果会因模型而异，但介于 -1 和 1 之间的值应该会减少或增加选择的可能性；像 -100 或 100 这样的值应该导致相关标记被禁止或独占选择。
#### `logprobs` [#logprobs]
* 类型：布尔值或 null
* 必需：否
* 默认值：false
是否返回输出标记的对数概率。如果为 true，则返回 `message.content` 中每个输出标记的对数概率。
#### `user` [#user]
* 类型：字符串
* 必需：否
表示最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。[了解更多](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)。
#### `service_tier` [#service_tier]
* 类型：字符串或 null
* 必需：否
* 默认值：auto
指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关：
* 如果设置为 'auto'，且项目启用了 Scale tier，系统将使用 scale tier 信用直到用完
* 如果设置为 'auto'，且项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
* 如果设置为 'default'，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
* 如果设置为 'flex'，请求将使用 Flex Processing 服务层级处理。详情请参阅文档。
* 未设置时，默认行为为 'auto'
* 当设置此参数时，响应体将包含使用的 service\_tier
#### `stream_options` [#stream_options]
* 类型：对象或 null
* 必需：否
* 默认值：null
流式响应的选项。仅在设置 `stream: true` 时使用。
**可能的属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------------- | --- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `include_usage` | 布尔值 | 否 | 如果设置，将在 data: \[DONE] 消息之前流式传输一个附加块。该块上的 usage 字段显示整个请求的令牌使用统计信息，choices 字段始终为空数组。所有其他块也将包含 usage 字段，但值为 null。注意：如果流被中断，您可能不会收到包含请求总令牌使用量的最终使用块。 |
#### `response_format` [#response_format]
* 类型：对象
* 必需：否
指定模型必须输出的格式。
* 设置为 `{ "type": "json_schema", "json_schema": {...} }` 启用结构化输出，确保模型将匹配您提供的 JSON schema。
* 设置为 `{ "type": "json_object" }` 启用 JSON 模式，确保模型生成的消息是有效的 JSON。
重要提示：使用 JSON 模式时，您还必须通过系统或用户消息自行指示模型生成 JSON。否则，模型可能会生成无尽的空白直到生成达到令牌限制。
**可能的类型：**
| 类型 | 描述 |
| ---------------- | --------------------------------------------------------- |
| **text** | 默认响应格式。用于生成文本响应。 |
| **json\_schema** | JSON Schema 响应格式。用于生成结构化 JSON 响应。了解更多关于结构化输出的信息。 |
| **json\_object** | JSON 对象响应格式。一种较老的生成 JSON 响应的方法。对于支持的模型，推荐使用 json\_schema。 |
**text 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | ----------------------- |
| `type` | 字符串 | 是 | 正在定义的响应格式类型。始终为 `text`。 |
**json\_schema 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --- | -- | ------------------------------ |
| `json_schema` | 对象 | 是 | 结构化输出配置选项，包括 JSON Schema。 |
| `type` | 字符串 | 是 | 正在定义的响应格式类型。始终为 `json_schema`。 |
**json\_schema.json\_schema 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --------- | -- | ------------------------------------------------------------------------------------------ |
| `name` | 字符串 | 是 | 响应格式的名称。必须是 a-z、A-Z、0-9 或包含下划线和破折号，最大长度为 64。 |
| `description` | 字符串 | 否 | 响应格式的用途描述，模型用它来确定如何以该格式响应。 |
| `schema` | 对象 | 否 | 响应格式的架构，描述为 JSON Schema 对象。 |
| `strict` | 布尔值或 null | 否 | 是否在生成输出时启用严格架构遵守。如果设置为 true，模型将始终遵循 schema 字段中定义的确切架构。strict 为 true 时，仅支持 JSON Schema 的子集。 |
**json\_object 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | ------------------------------ |
| `type` | 字符串 | 是 | 正在定义的响应格式类型。始终为 `json_object`。 |
#### `seed` [#seed]
* 类型：整数或 null
* 必需：否
Beta 功能。如果指定，我们的系统将尽最大努力进行确定性采样，使得具有相同 seed 和参数的重复请求应返回相同的结果。不保证确定性，您应参考响应参数的 system\_fingerprint 以监控后端的变化。
#### `tools` [#tools]
* 类型：数组
* 必需：否
模型可能调用的工具列表。目前仅支持函数作为工具。使用此参数提供模型可能生成 JSON 输入的函数列表。最多支持 128 个函数。
**属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ---------------------- |
| `function` | 对象 | 是 | 要调用的函数信息 |
| `type` | 字符串 | 是 | 工具的类型。目前，仅支持 function。 |
**function 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --------- | -- | ----------------------------------------------------------------------------------------------------------------------------- |
| `name` | 字符串 | 是 | 要调用的函数名称。必须是a-z、A-Z、0-9，或包含下划线和破折号，最大长度为64。 |
| `description` | 字符串 | 否 | 函数功能的描述，模型用它来选择何时以及如何调用函数。 |
| `parameters` | 对象 | 否 | 函数接受的参数，描述为JSON Schema对象。请参阅指南获取示例，以及JSON Schema参考了解格式文档。省略parameters定义一个空参数列表的函数。 |
| `strict` | 布尔值或 null | 否 | 默认值：false。是否在生成函数调用时启用严格架构遵守。如果设置为 true，模型将遵循 parameters 字段中定义的确切架构。strict 为 true 时，仅支持 JSON Schema 的子集。详情请参阅函数调用指南中的结构化输出部分。 |
#### `functions` [#functions]
* 类型：数组
* 必需：否
* 注意：已弃用，推荐使用 `tools`
模型可能生成 JSON 输入的函数列表。
| 属性 | 类型 | 必需 | 描述 |
| ------------- | --- | -- | -------------------------------------------------- |
| `name` | 字符串 | 是 | 要调用的函数名称。必须是a-z、A-Z、0-9，或包含下划线和破折号，最大长度为64。 |
| `description` | 字符串 | 否 | 函数功能的描述，模型用它来选择何时以及如何调用函数。 |
| `parameters` | 对象 | 否 | 函数接受的参数，描述为JSON Schema对象。省略parameters定义一个空参数列表的函数。 |
#### `tool_choice` [#tool_choice]
* 类型：字符串或对象
* 必需：否
控制模型调用哪个工具（如果有）：
* `none`：模型不会调用任何工具，而是生成消息
* `auto`：模型可以在生成消息或调用一个或多个工具之间选择
* `required`：模型必须调用一个或多个工具
* `{"type": "function", "function": {"name": "my_function"}}`：强制模型调用特定工具
当没有工具时默认为 `none`，有工具时默认为 `auto`。
**可能的类型：**
| 类型 | 描述 |
| ------- | --------------------------------------------------------------------------------- |
| **字符串** | none 表示模型不会调用任何工具，而是生成消息。auto 表示模型可以在生成消息或调用一个或多个工具之间选择。required 表示模型必须调用一个或多个工具。 |
| **对象** | 指定模型应使用的工具。用于强制模型调用特定函数。 |
**对象属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ---------------------- |
| `function` | 对象 | 是 | 包含函数信息的对象 |
| `type` | 字符串 | 是 | 工具的类型。目前，仅支持 function。 |
**function 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | --------- |
| `name` | 字符串 | 是 | 要调用的函数名称。 |
#### `function_call` [#function_call]
* 类型：字符串或对象
* 必需：否
* 默认值：没有函数时为 `none`，有函数时为 `auto`
* 注意：已弃用，推荐使用 `tool_choice`
控制模型调用哪个函数（如果有）：
* `none`：模型不会调用函数，而是生成消息
* `auto`：模型可以在生成消息或调用函数之间选择
* `{"name": "my_function"}`：强制模型调用特定函数
**对象类型属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | --------- |
| `name` | 字符串 | 是 | 要调用的函数名称。 |
#### `parallel_tool_calls` [#parallel_tool_calls]
* 类型：布尔值
* 必需：否
* 默认值：true
是否在工具使用期间启用并行函数调用。
#### `stream` [#stream]
* 类型：布尔值或 null
* 必需：否
* 默认值：false
如果设置为 true，模型响应数据将在生成时通过服务器发送事件流式传输到客户端。请参阅下方的流式响应部分获取更多信息，以及流式响应指南了解如何处理流式事件。
#### `top_logprobs` [#top_logprobs]
* 类型：整数或 null
* 必需：否
0 到 20 之间的整数，指定在每个标记位置返回的最可能标记的数量，每个标记都有关联的对数概率。如果使用此参数，必须将 `logprobs` 设置为 true。
#### `web_search_options` [#web_search_options]
* 类型：对象
* 必需：否
此工具搜索网络以获取相关结果用于回复。了解更多关于网络搜索工具的信息。
**可能的属性：**
| 属性 | 类型 | 必需 | 描述 |
| --------------------- | -------- | -- | ----------------------------------------------------------------- |
| `search_context_size` | 字符串 | 否 | 默认值：medium。用于搜索的上下文窗口空间量的高级指导。可选值为 low、medium 或 high。medium 是默认值。 |
| `user_location` | 对象或 null | 否 | 搜索的近似位置参数。 |
**user\_location 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ------------- | -- | -- | ---------- |
| `approximate` | 对象 | 是 | 搜索的近似位置参数。 |
**approximate 属性：**
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ------------------------------------ |
| `city` | 字符串 | 否 | 用户城市的自由文本输入，例如 San Francisco。 |
| `country` | 字符串 | 否 | 用户的两字母 ISO 国家代码，例如 US。 |
| `region` | 字符串 | 否 | 用户地区的自由文本输入，例如 California。 |
| `timezone` | 字符串 | 否 | 用户的 IANA 时区，例如 America/Los\_Angeles。 |
| `type` | 字符串 | 是 | 位置近似类型。始终为 approximate。 |
## 📥 响应 [#-响应]
### 聊天补全对象 [#聊天补全对象]
返回一个聊天补全对象,如果请求被流式传输,则返回聊天补全块对象的流式序列。
#### `id` [#id]
* 类型：字符串
* 说明：响应的唯一标识符
#### `object` [#object]
* 类型：字符串
* 说明：对象类型,值为 "chat.completion"
#### `created` [#created]
* 类型：整数
* 说明：响应创建时间戳
#### `model` [#model-1]
* 类型：字符串
* 说明：使用的模型名称
#### `system_fingerprint` [#system_fingerprint]
* 类型：字符串
* 说明：系统指纹标识符，表示模型运行的后端配置。可以与seed请求参数一起使用，以了解何时进行了可能影响确定性的后端更改。
#### `choices` [#choices]
* 类型：数组
* 说明：包含生成的回复选项列表。如果 n 大于 1，则可以有多个选项。
* 属性:
* `index`: 选项在选项列表中的索引。
* `message`: 模型生成的聊天补全消息。
* `role`: 消息作者的角色。
* `content`: 消息的内容，可能为 null。
* `refusal`: 模型生成的拒绝消息，可能为 null。
* `annotations`: 消息的注释，在适用时提供，例如使用网络搜索工具时。
* `type`: 注释类型，URL引用时始终为 "url\_citation"。
* `url_citation`: 使用网络搜索时的URL引用。
* `start_index`: URL引用在消息中的第一个字符的索引。
* `end_index`: URL引用在消息中的最后一个字符的索引。
* `url`: 网络资源的URL。
* `title`: 网络资源的标题。
* `audio`: 如果请求了音频输出模态，此对象包含来自模型的音频响应的数据。
* `data`: 模型生成的Base64编码音频字节，格式在请求中指定。
* `id`: 此音频响应的唯一标识符。
* `transcript`: 模型生成的音频的转录。
* `expires_at`: 此音频响应在服务器上可用于多轮对话的Unix时间戳（秒）。
* `function_call`: （已弃用）应调用的函数的名称和参数，由模型生成。已被 `tool_calls` 替代。
* `name`: 要调用的函数的名称。
* `arguments`: 用于调用函数的参数，由模型以JSON格式生成。
* `tool_calls`: 模型生成的工具调用，如函数调用。
* `id`: 工具调用的ID。
* `type`: 工具的类型。目前，仅支持 function。
* `function`: 模型调用的函数。
* `name`: 要调用的函数的名称。
* `arguments`: 用于调用函数的参数，由模型以JSON格式生成。注意，模型并不总是生成有效的JSON，并且可能会产生您函数架构中未定义的参数。在调用函数之前，请在代码中验证参数。
* `logprobs`: 对数概率信息。
* `content`: 带有对数概率信息的消息内容标记列表。
* `token`: 标记。
* `logprob`: 此标记的对数概率，如果它在前20个最可能的标记内。否则，使用-9999.0的值表示此标记非常不可能。
* `bytes`: 表示标记的UTF-8字节表示的整数列表。在字符由多个标记表示且必须组合它们的字节表示以生成正确的文本表示的情况下很有用。如果标记没有字节表示，则可能为null。
* `top_logprobs`: 在此标记位置上最可能的标记及其对数概率的列表。在罕见情况下，返回的top\_logprobs数量可能少于请求的数量。
* `refusal`: 带有对数概率信息的消息拒绝标记列表。
* `finish_reason`: 模型停止生成标记的原因。如果模型到达自然停止点或提供的停止序列，则为 "stop"；如果达到请求中指定的最大标记数，则为 "length"；如果由于内容过滤器标记而省略内容，则为 "content\_filter"；如果模型调用了工具，则为 "tool\_calls"；如果模型调用了函数，则为 "function\_call"（已弃用）。
#### `usage` [#usage]
* 类型：对象
* 说明：补全请求的使用统计信息。
* 属性:
* `prompt_tokens`: 提示中的标记数。
* `completion_tokens`: 生成的补全中的标记数。
* `total_tokens`: 请求中使用的标记总数（提示 + 补全）。
* `prompt_tokens_details`: 提示中使用的标记的细分。
* `cached_tokens`: 提示中存在的缓存标记。
* `audio_tokens`: 提示中存在的音频输入标记。
* `completion_tokens_details`: 补全中使用的标记的细分。
* `reasoning_tokens`: 模型生成的推理标记。
* `audio_tokens`: 模型生成的音频标记。
* `accepted_prediction_tokens`: 使用预测输出时，预测中出现在补全中的标记数。
* `rejected_prediction_tokens`: 使用预测输出时，预测中未出现在补全中的标记数。但是，与推理标记一样，这些标记仍计入计费、输出和上下文窗口限制的总补全标记中。
#### `service_tier` [#service_tier-1]
* 类型：字符串或 null
* 说明：指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关：
* 如果设置为 'auto'，且项目启用了 Scale tier，系统将使用 scale tier 信用直到用完
* 如果设置为 'auto'，且项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
* 如果设置为 'default'，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证
* 如果设置为 'flex'，请求将使用 Flex Processing 服务层级处理
* 未设置时，默认行为为 'auto'
* 当设置此参数时，响应体将包含使用的 service\_tier
#### 聊天补全对象响应示例 [#聊天补全对象响应示例]
```json
{
"id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
"object": "chat.completion",
"created": 1741570283,
"model": "gpt-4o-2024-08-06",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "图片展示了一条穿过茂密绿色草地或草甸的木制栈道。天空湛蓝，点缀着几朵散落的云彩，给整个场景营造出宁静祥和的氛围。背景中可以看到树木和灌木丛。",
"refusal": null,
"annotations": []
},
"logprobs": null,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1117,
"completion_tokens": 46,
"total_tokens": 1163,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"completion_tokens_details": {
"reasoning_tokens": 0,
"audio_tokens": 0,
"accepted_prediction_tokens": 0,
"rejected_prediction_tokens": 0
}
},
"service_tier": "default",
"system_fingerprint": "fp_fc9f1d7035"
}
```
### 聊天补全列表对象 [#聊天补全列表对象]
当返回多个聊天补全时，API 可能会返回聊天补全列表对象。
#### `object` [#object-1]
* 类型：字符串
* 说明：对象类型，始终为 "list"
#### `data` [#data]
* 类型：数组
* 说明：聊天补全对象的数组
#### `first_id` [#first_id]
* 类型：字符串
* 说明：数据数组中第一个聊天补全的标识符
#### `last_id` [#last_id]
* 类型：字符串
* 说明：数据数组中最后一个聊天补全的标识符
#### `has_more` [#has_more]
* 类型：布尔值
* 说明：表示是否有更多聊天补全可用
#### 聊天补全列表响应示例 [#聊天补全列表响应示例]
```json
{
"object": "list",
"data": [
{
"object": "chat.completion",
"id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"model": "gpt-4o-2024-08-06",
"created": 1738960610,
"request_id": "req_ded8ab984ec4bf840f37566c1011c417",
"tool_choice": null,
"usage": {
"total_tokens": 31,
"completion_tokens": 18,
"prompt_tokens": 13
},
"seed": 4944116822809979520,
"top_p": 1.0,
"temperature": 1.0,
"presence_penalty": 0.0,
"frequency_penalty": 0.0,
"system_fingerprint": "fp_50cad350e4",
"input_user": null,
"service_tier": "default",
"tools": null,
"metadata": {},
"choices": [
{
"index": 0,
"message": {
"content": "电路之心低吟，\n在寂静中学习模式—\n未来的宁静火花。",
"role": "assistant",
"tool_calls": null,
"function_call": null
},
"finish_reason": "stop",
"logprobs": null
}
],
"response_format": null
}
],
"first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2",
"has_more": false
}
```
### 聊天补全消息列表对象 [#聊天补全消息列表对象]
聊天补全消息列表对象表示聊天消息的列表。
#### `object` [#object-2]
* 类型：字符串
* 说明：对象类型，始终为 "list"
#### `data` [#data-1]
* 类型：数组
* 说明：聊天补全消息对象的数组，每个消息对象包含以下属性：
* `id`: 聊天消息的标识符
* `role`: 消息作者的角色
* `content`: 消息的内容，可能为 null
* `name`: 消息发送者的名称，可能为 null
* `refusal`: 模型生成的拒绝消息，可能为 null
* `annotations`: 消息的注释，在适用时提供，例如使用网络搜索工具时
* `type`: 注释类型，URL引用时始终为 "url\_citation"
* `url_citation`: 使用网络搜索时的URL引用
* `start_index`: URL引用在消息中的第一个字符的索引
* `end_index`: URL引用在消息中的最后一个字符的索引
* `url`: 网络资源的URL
* `title`: 网络资源的标题
* `audio`: 如果请求了音频输出模态，此对象包含来自模型的音频响应的数据
* `data`: 模型生成的Base64编码音频字节，格式在请求中指定
* `id`: 此音频响应的唯一标识符
* `transcript`: 模型生成的音频的转录
* `expires_at`: 此音频响应在服务器上可用于多轮对话的Unix时间戳（秒）
* `function_call`: （已弃用）应调用的函数的名称和参数，由模型生成。已被 `tool_calls` 替代
* `name`: 要调用的函数的名称
* `arguments`: 用于调用函数的参数，由模型以JSON格式生成
* `tool_calls`: 模型生成的工具调用，如函数调用
* `id`: 工具调用的ID
* `type`: 工具的类型。目前，仅支持 function
* `function`: 模型调用的函数
* `name`: 要调用的函数的名称
* `arguments`: 用于调用函数的参数，由模型以JSON格式生成
#### `first_id` [#first_id-1]
* 类型：字符串
* 说明：数据数组中第一个聊天消息的标识符
#### `last_id` [#last_id-1]
* 类型：字符串
* 说明：数据数组中最后一个聊天消息的标识符
#### `has_more` [#has_more-1]
* 类型：布尔值
* 说明：表示是否有更多聊天消息可用
#### 聊天补全消息列表响应示例 [#聊天补全消息列表响应示例]
```json
{
"object": "list",
"data": [
{
"id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"role": "user",
"content": "写一首关于人工智能的俳句",
"name": null,
"content_parts": null
}
],
"first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2-0",
"has_more": false
}
```
# OpenAI 嵌入格式（Embeddings） (/zh/api/openai-embedding)
[OpenAI Embeddings](https://platform.openai.com/docs/api-reference/embeddings)
## 📝 简介 [#-简介]
获取给定输入文本的向量表示，这些向量可以被机器学习模型和算法轻松使用。相关指南请参阅 [Embeddings Guide](https://platform.openai.com/docs/guides/embeddings)。
需要注意的是:
* 某些模型可能对输入的总 token 数有限制
* 您可以使用[示例 Python 代码](https://github.com/openai/openai-cookbook/blob/main/examples/How_to_count_tokens_with_tiktoken.ipynb)来计算 token 数量
* 例如：text-embedding-ada-002 模型的输出向量维度为 1536
## 💡 请求示例 [#-请求示例]
### 创建文本嵌入 ✅ [#创建文本嵌入-]
```bash
curl https://api.zipflow.xyz/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"input": "The food was delicious and the waiter...",
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'
```
**响应示例:**
```json
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
-0.009327292,
// ... (1536 个浮点数,用于 ada-002)
-0.0028842222
],
"index": 0
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 8,
"total_tokens": 8
}
}
```
### 批量创建嵌入 ✅ [#批量创建嵌入-]
```bash
curl https://api.zipflow.xyz/v1/embeddings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"input": ["The food was delicious", "The waiter was friendly"],
"model": "text-embedding-ada-002",
"encoding_format": "float"
}'
```
**响应示例:**
```json
{
"object": "list",
"data": [
{
"object": "embedding",
"embedding": [
0.0023064255,
// ... (1536 个浮点数)
],
"index": 0
},
{
"object": "embedding",
"embedding": [
-0.008815289,
// ... (1536 个浮点数)
],
"index": 1
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 12,
"total_tokens": 12
}
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/embeddings
```
创建表示输入文本的嵌入向量。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$OPENAI_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### `input` [#input]
* 类型：字符串或数组
* 必需：是
要嵌入的输入文本,编码为字符串或 token 数组。要在单个请求中嵌入多个输入,请传递字符串数组或 token 数组的数组。输入不得超过模型的最大输入 token 数(text-embedding-ada-002 为 8192 个 token),不能为空字符串,任何数组的维度必须小于等于 2048。
#### `model` [#model]
* 类型：字符串
* 必需：是
要使用的模型 ID。您可以使用 List models API 查看所有可用模型,或查看模型概述了解它们的描述。
#### `encoding_format` [#encoding_format]
* 类型：字符串
* 必需：否
* 默认值：float
返回嵌入的格式。可以是 float 或 base64。
#### `dimensions` [#dimensions]
* 类型：整数
* 必需：否
生成的输出嵌入应具有的维度数。仅在 text-embedding-3 及更高版本的模型中支持。
#### `user` [#user]
* 类型：字符串
* 必需：否
代表您的最终用户的唯一标识符,可以帮助 OpenAI 监控和检测滥用行为。[了解更多](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)。
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
返回嵌入对象列表。
#### `object` [#object]
* 类型：字符串
* 说明：对象类型,值为 "list"
#### `data` [#data]
* 类型：数组
* 说明：包含嵌入对象的数组
* 属性:
* `object`: 对象类型,值为 "embedding"
* `embedding`: 嵌入向量,浮点数列表。向量长度取决于模型
* `index`: 嵌入在列表中的索引
#### `model` [#model-1]
* 类型：字符串
* 说明：使用的模型名称
#### `usage` [#usage]
* 类型：对象
* 说明：token 使用统计
* 属性:
* `prompt_tokens`: 提示使用的 token 数
* `total_tokens`: 总 token 数
### 嵌入对象 [#嵌入对象]
表示由嵌入端点返回的嵌入向量。
```json
{
"object": "embedding",
"embedding": [
0.0023064255,
-0.009327292,
// ... (ada-002 总共 1536 个浮点数)
-0.0028842222
],
"index": 0
}
```
#### `index` [#index]
* 类型：整数
* 说明：嵌入在列表中的索引
#### `embedding` [#embedding]
* 类型：数组
* 说明：嵌入向量,浮点数列表。向量长度取决于模型,具体请参阅嵌入指南
#### `object` [#object-1]
* 类型：字符串
* 说明：对象类型,始终为 "embedding"
### 错误响应 [#错误响应]
当请求出现问题时，API 将返回一个错误响应对象，HTTP 状态码在 4XX-5XX 范围内。
#### 常见错误状态码 [#常见错误状态码]
* `401 Unauthorized`: API 密钥无效或未提供
* `400 Bad Request`: 请求参数无效，例如输入为空或超出 token 限制
* `429 Too Many Requests`: 超出 API 调用限制
* `500 Internal Server Error`: 服务器内部错误
错误响应示例:
```json
{
"error": {
"message": "The input exceeds the maximum length. Please reduce the length of your input.",
"type": "invalid_request_error",
"param": "input",
"code": "context_length_exceeded"
}
}
```
# OpenAI 图像格式（Image） (/zh/api/openai-image)
[OpenAI Images](https://platform.openai.com/docs/api-reference/images)
## 📝 简介 [#-简介]
给定文本提示和/或输入图片，模型将生成新的图片。OpenAI 提供多种强大的图像生成模型，可以根据自然语言描述创建、编辑和修改图像。目前支持的模型包括：
| 模型 | 描述 |
| --------------- | --------------------------------------------------- |
| **DALL·E 系列** | 包括 DALL·E 2 和 DALL·E 3 两个版本，它们在图像质量、创意表现和精确度上都有显著差异 |
| **GPT-Image-1** | OpenAI最新图片模型，支持多图片编辑功能，能够基于多个输入图像创建新的组合图像 |
## 💡 请求示例 [#-请求示例]
### 创建图片 ✅ [#创建图片-]
```bash
# 基础图片生成
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"n": 1,
"size": "1024x1024"
}'
# 高质量图片生成
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"quality": "hd",
"style": "vivid",
"size": "1024x1024"
}'
# 使用 base64 返回格式
curl https://api.zipflow.xyz/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "dall-e-3",
"prompt": "一只可爱的小海獭",
"response_format": "b64_json"
}'
```
**响应示例:**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://...",
"revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}
]
}
```
### 编辑图片 ✅ [#编辑图片-]
```bash
# dall-e-2 图片编辑
curl https://api.zipflow.xyz/v1/images/edits \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F image="@otter.png" \
-F mask="@mask.png" \
-F prompt="一只戴着贝雷帽的可爱小海獭" \
-F n=2 \
-F size="1024x1024"
# gpt-image-1 多图片编辑示例
curl https://api.zipflow.xyz/v1/images/edits \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F "model=gpt-image-1" \
-F "image[]=@body-lotion.png" \
-F "image[]=@bath-bomb.png" \
-F "image[]=@incense-kit.png" \
-F "image[]=@soap.png" \
-F "prompt=创建一个包含这四个物品的精美礼品篮" \
-F "quality=high"
```
**响应示例 (dall-e-2):**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}
```
**响应示例 (gpt-image-1):**
```json
{
"created": 1713833628,
"data": [
{
"b64_json": "..."
}
],
"usage": {
"total_tokens": 100,
"input_tokens": 50,
"output_tokens": 50,
"input_tokens_details": {
"text_tokens": 10,
"image_tokens": 40
}
}
}
```
### 生成图片变体 ✅ [#生成图片变体-]
```bash
curl https://api.zipflow.xyz/v1/images/variations \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-F image="@otter.png" \
-F n=2 \
-F size="1024x1024"
```
**响应示例:**
```json
{
"created": 1589478378,
"data": [
{
"url": "https://..."
},
{
"url": "https://..."
}
]
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
#### 创建图片 [#创建图片]
```
POST /v1/images/generations
```
根据文本提示创建图片。
#### 编辑图片 [#编辑图片]
```
POST /v1/images/edits
```
根据一个或多个原始图片和提示创建编辑或扩展的图片。此端点支持 dall-e-2 和 gpt-image-1 模型。
#### 生成变体 [#生成变体]
```
POST /v1/images/variations
```
创建给定图片的变体。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$OPENAI_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### 创建图片 [#创建图片-1]
##### `prompt` [#prompt]
* 类型：字符串
* 必需：是
* 说明：期望生成图片的文本描述。
* dall-e-2 最大长度为 1000 字符
* dall-e-3 最大长度为 4000 字符
* 提示：
* 使用具体和详细的描述
* 包含关键的视觉元素
* 指定期望的艺术风格
* 描述构图和视角
##### `model` [#model]
* 类型：字符串
* 必需：否
* 默认值：dall-e-2
* 说明：用于图像生成的模型。
##### `n` [#n]
* 类型：整数或 null
* 必需：否
* 默认值：1
* 说明：要生成的图片数量。必须在 1-10 之间。dall-e-3 仅支持 n=1。
##### `quality` [#quality]
* 类型：字符串
* 必需：否
* 默认值：standard
* 说明：生成图片的质量。hd 选项会生成更细致和一致的图片。仅 dall-e-3 支持此参数。
##### `response_format` [#response_format]
* 类型：字符串或 null
* 必需：否
* 默认值：url
* 说明：返回生成图片的格式。必须是 url 或 b64\_json 之一。URL 在生成后 60 分钟内有效。
##### `size` [#size]
* 类型：字符串或 null
* 必需：否
* 默认值：1024x1024
* 说明：生成图片的尺寸。dall-e-2 必须是 256x256、512x512 或 1024x1024 之一。dall-e-3 必须是 1024x1024、1792x1024 或 1024x1792 之一。
##### `style` [#style]
* 类型：字符串或 null
* 必需：否
* 默认值：vivid
* 说明：生成图片的风格。必须是 vivid 或 natural 之一。vivid 倾向于生成超现实和戏剧性的图片，natural 倾向于生成更自然、不那么超现实的图片。仅 dall-e-3 支持此参数。
##### `user` [#user]
* 类型：字符串
* 必需：否
* 说明：代表最终用户的唯一标识符，可帮助 OpenAI 监控和检测滥用行为。
#### `moderation` [#moderation]
* 类型：字符串
* 必需：否
* 默认值：auto
* 说明：auto：标准审核，旨在限制生成某些可能不适合年龄的内容类别。low：限制较少的审核。
#### 编辑图片 [#编辑图片-1]
##### `image` [#image]
* 类型：文件或文件数组
* 必需：是
* 说明：要编辑的图片。
* 对于 dall-e-2：必须是有效的 PNG 文件，小于 4MB，且为正方形。如果未提供 mask，图片必须具有透明度，这将用作蒙版。
* 对于 gpt-image-1：可以提供多个图片作为数组，每个图片应为 PNG、WEBP 或 JPG 文件，小于 25MB。
##### `prompt` [#prompt-1]
* 类型：字符串
* 必需：是
* 说明：期望生成图片的文本描述。
* dall-e-2 最大长度为 1000 字符
* gpt-image-1 最大长度为 32000 字符
##### `mask` [#mask]
* 类型：文件
* 必需：否
* 说明：额外的图片，其完全透明区域（如 alpha 为零的区域）指示应该编辑的位置。如果提供了多个图片，mask 将应用于第一张图片。必须是有效的 PNG 文件，小于 4MB，且与 image 具有相同尺寸。
##### `model` [#model-1]
* 类型：字符串
* 必需：否
* 默认值：dall-e-2
* 说明：用于图像生成的模型。支持 dall-e-2 和 gpt-image-1。除非使用了 gpt-image-1 特有的参数，否则默认为 dall-e-2。
##### `quality` [#quality-1]
* 类型：字符串或 null
* 必需：否
* 默认值：auto
* 说明：生成图片的质量。
* gpt-image-1 支持 high、medium 和 low
* dall-e-2 仅支持 standard
* 默认为 auto
##### `size` [#size-1]
* 类型：字符串或 null
* 必需：否
* 默认值：1024x1024
* 说明：生成图片的尺寸。
* gpt-image-1 必须是 1024x1024、1536x1024（横版）、1024x1536（竖版）或 auto（默认）之一
* dall-e-2 必须是 256x256、512x512 或 1024x1024 之一
其他参数与创建图片接口相同。
#### 生成变体 [#生成变体-1]
##### `image` [#image-1]
* 类型：文件
* 必需：是
* 说明：作为变体基础的图片。必须是有效的 PNG 文件，小于 4MB，且为正方形。
其他参数与创建图片接口相同。
## 📥 响应 [#-响应]
### 成功响应 [#成功响应]
所有三个端点都返回包含图片对象列表的响应。
#### `created` [#created]
* 类型：整数
* 说明：响应创建的时间戳
#### `data` [#data]
* 类型：数组
* 说明：生成的图片对象列表
#### `usage`（仅适用于 gpt-image-1） [#usage仅适用于-gpt-image-1]
* 类型：对象
* 说明：API 调用的令牌使用情况
* `total_tokens`：使用的总令牌数
* `input_tokens`：输入使用的令牌数
* `output_tokens`：输出使用的令牌数
* `input_tokens_details`：输入令牌的详细信息（文本令牌和图像令牌）
### 图片对象 [#图片对象]
#### `b64_json` [#b64_json]
* 类型：字符串
* 说明：如果 response\_format 为 b64\_json，则包含生成图片的 base64 编码 JSON
#### `url` [#url]
* 类型：字符串
* 说明：如果 response\_format 为 url（默认），则包含生成图片的 URL
#### `revised_prompt` [#revised_prompt]
* 类型：字符串
* 说明：如果提示有任何修改，则包含用于生成图片的修改后的提示
示例图片对象:
```json
{
"url": "https://...",
"revised_prompt": "一只可爱的小海獭在水中嬉戏,它有着圆圆的眼睛和毛茸茸的皮毛"
}
```
## 🌟 最佳实践 [#-最佳实践]
### Prompt 编写建议 [#prompt-编写建议]
1. 使用清晰具体的描述
2. 指定重要的视觉细节
3. 描述期望的艺术风格和氛围
4. 注意构图和视角的说明
### 参数选择建议 [#参数选择建议]
1. 模型选择
* dall-e-3：适合需要高质量、精确细节的场景
* dall-e-2：适合快速原型或简单图像生成
2. 尺寸选择
* 1024x1024：通用场景的最佳选择
* 1792x1024/1024x1792：适合横版/竖版场景
* 较小尺寸：适合缩略图或快速预览
3. 质量和风格
* quality=hd：用于需要精细细节的图像
* style=vivid：适合创意和艺术效果
* style=natural：适合真实场景再现
### 常见问题 [#常见问题]
1. 图片生成失败
* 检查 prompt 是否符合内容政策
* 确认文件格式和大小限制
* 验证 API 密钥权限
2. 结果与预期不符
* 优化 prompt 描述
* 调整质量和风格参数
* 考虑使用图片编辑或变体功能
# OpenAI 实时对话接口 (/zh/api/openai-realtime)
* [OpenAI Realtime WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc)
* [OpenAI Realtime WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
## 📝 概述 [#-概述]
### 简介 [#简介]
OpenAI Realtime API 提供两种连接方式：
1. WebRTC - 适用于浏览器和移动客户端的实时音视频交互
2. WebSocket - 适用于服务器到服务器的应用程序集成
### 使用场景 [#使用场景]
* 实时语音对话
* 音视频会议
* 实时翻译
* 语音转写
* 实时代码生成
* 服务器端实时集成
### 主要特性 [#主要特性]
* 双向音频流传输
* 文本和音频混合对话
* 函数调用支持
* 自动语音检测(VAD)
* 音频转写功能
* WebSocket 服务器端集成
## 🔐 认证与安全 [#-认证与安全]
### 认证方式 [#认证方式]
1. 标准 API 密钥 (仅服务器端使用)
2. 临时令牌 (客户端使用)
### 临时令牌 [#临时令牌]
* 有效期: 1分钟
* 使用限制: 单个连接
* 获取方式: 通过服务器端 API 创建
```http
POST https://api.zipflow.xyz/v1/realtime/sessions
Content-Type: application/json
Authorization: Bearer $API_KEY
{
"model": "gpt-4o-realtime-preview-2024-12-17",
"voice": "verse"
}
```
### 安全建议 [#安全建议]
* 永远不要在客户端暴露标准 API 密钥
* 使用 HTTPS/WSS 进行通信
* 实现适当的访问控制
* 监控异常活动
## 🔌 连接建立 [#-连接建立]
### WebRTC 连接 [#webrtc-连接]
* URL: `https://api.zipflow.xyz/v1/realtime`
* 查询参数: `model`
* 请求头:
* `Authorization: Bearer EPHEMERAL_KEY`
* `Content-Type: application/sdp`
### WebSocket 连接 [#websocket-连接]
* URL: `wss://api.zipflow.xyz/v1/realtime`
* 查询参数: `model`
* 请求头:
* `Authorization: Bearer YOUR_API_KEY`
* `OpenAI-Beta: realtime=v1`
### 连接流程 [#连接流程]
```mermaid
sequenceDiagram
participant Client
participant Server
participant OpenAI
alt WebRTC 连接
Client->>Server: 请求临时令牌
Server->>OpenAI: 创建会话
OpenAI-->>Server: 返回临时令牌
Server-->>Client: 返回临时令牌
Client->>OpenAI: 创建 WebRTC offer
OpenAI-->>Client: 返回 answer
Note over Client,OpenAI: 建立 WebRTC 连接
Client->>OpenAI: 创建数据通道
OpenAI-->>Client: 确认数据通道
else WebSocket 连接
Server->>OpenAI: 建立 WebSocket 连接
OpenAI-->>Server: 确认连接
Note over Server,OpenAI: 开始实时对话
end
```
### 数据通道 [#数据通道]
* 名称: `oai-events`
* 用途: 事件传输
* 格式: JSON
### 音频流 [#音频流]
* 输入: `addTrack()`
* 输出: `ontrack` 事件
## 💬 对话交互 [#-对话交互]
### 对话模式 [#对话模式]
1. 纯文本对话
2. 语音对话
3. 混合对话
### 会话管理 [#会话管理]
* 创建会话
* 更新会话
* 结束会话
* 会话配置
### 事件类型 [#事件类型]
* 文本事件
* 音频事件
* 函数调用
* 状态更新
* 错误事件
## ⚙️ 配置选项 [#️-配置选项]
### 音频配置 [#音频配置]
* 输入格式
* `pcm16`
* `g711_ulaw`
* `g711_alaw`
* 输出格式
* `pcm16`
* `g711_ulaw`
* `g711_alaw`
* 语音类型
* `alloy`
* `echo`
* `shimmer`
### 模型配置 [#模型配置]
* 温度
* 最大输出长度
* 系统提示词
* 工具配置
### VAD 配置 [#vad-配置]
* 阈值
* 静音时长
* 前缀填充
## 💡 请求示例 [#-请求示例]
### WebRTC 连接 ❌ [#webrtc-连接-]
#### 客户端实现 (浏览器) [#客户端实现-浏览器]
```javascript
async function init() {
// 从服务器获取临时密钥 - 参见下方服务器代码
const tokenResponse = await fetch("/session");
const data = await tokenResponse.json();
const EPHEMERAL_KEY = data.client_secret.value;
// 创建对等连接
const pc = new RTCPeerConnection();
// 设置播放模型返回的远程音频
const audioEl = document.createElement("audio");
audioEl.autoplay = true;
pc.ontrack = e => audioEl.srcObject = e.streams[0];
// 添加浏览器麦克风输入的本地音频轨道
const ms = await navigator.mediaDevices.getUserMedia({
audio: true
});
pc.addTrack(ms.getTracks()[0]);
// 设置用于发送和接收事件的数据通道
const dc = pc.createDataChannel("oai-events");
dc.addEventListener("message", (e) => {
// 这里接收实时服务器事件！
console.log(e);
});
// 使用会话描述协议(SDP)启动会话
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
const baseUrl = "https://api.zipflow.xyz/v1/realtime";
const model = "gpt-4o-realtime-preview-2024-12-17";
const sdpResponse = await fetch(`${baseUrl}?model=${model}`, {
method: "POST",
body: offer.sdp,
headers: {
Authorization: `Bearer ${EPHEMERAL_KEY}`,
"Content-Type": "application/sdp"
},
});
const answer = {
type: "answer",
sdp: await sdpResponse.text(),
};
await pc.setRemoteDescription(answer);
}
init();
```
#### 服务器端实现 (Node.js) [#服务器端实现-nodejs]
```javascript
import express from "express";
const app = express();
// 创建一个端点用于生成临时令牌
// 该端点与上面的客户端代码配合使用
app.get("/session", async (req, res) => {
const r = await fetch("https://api.zipflow.xyz/v1/realtime/sessions", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-4o-realtime-preview-2024-12-17",
voice: "verse",
}),
});
const data = await r.json();
// 将从OpenAI REST API收到的JSON发送回客户端
res.send(data);
});
app.listen(3000);
```
#### WebRTC 事件收发示例 [#webrtc-事件收发示例]
```javascript
// 从对等连接创建数据通道
const dc = pc.createDataChannel("oai-events");
// 监听数据通道上的服务器事件
// 事件数据需要从JSON字符串解析
dc.addEventListener("message", (e) => {
const realtimeEvent = JSON.parse(e.data);
console.log(realtimeEvent);
});
// 发送客户端事件：将有效的客户端事件序列化为
// JSON，并通过数据通道发送
const responseCreate = {
type: "response.create",
response: {
modalities: ["text"],
instructions: "Write a haiku about code",
},
};
dc.send(JSON.stringify(responseCreate));
```
### WebSocket 连接 ✅ [#websocket-连接-]
#### Node.js (ws模块) [#nodejs-ws模块]
```javascript
import WebSocket from "ws";
const url = "wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17";
const ws = new WebSocket(url, {
headers: {
"Authorization": "Bearer " + process.env.API_KEY,
"OpenAI-Beta": "realtime=v1",
},
});
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(JSON.parse(message.toString()));
});
```
#### Python (websocket-client) [#python-websocket-client]
```python
# 需要安装 websocket-client 库:
# pip install websocket-client
import os
import json
import websocket
API_KEY = os.environ.get("API_KEY")
url = "wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17"
headers = [
"Authorization: Bearer " + API_KEY,
"OpenAI-Beta: realtime=v1"
]
def on_open(ws):
print("Connected to server.")
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
ws = websocket.WebSocketApp(
url,
header=headers,
on_open=on_open,
on_message=on_message,
)
ws.run_forever()
```
#### 浏览器 (标准WebSocket) [#浏览器-标准websocket]
```javascript
/*
注意：在浏览器等客户端环境中，我们建议使用WebRTC。
但在Deno和Cloudflare Workers等类浏览器环境中，
也可以使用标准WebSocket接口。
*/
const ws = new WebSocket(
"wss://api.zipflow.xyz/v1/realtime?model=gpt-4o-realtime-preview-2024-12-17",
[
"realtime",
// 认证
"openai-insecure-api-key." + API_KEY,
// 可选
"openai-organization." + OPENAI_ORG_ID,
"openai-project." + OPENAI_PROJECT_ID,
// Beta协议，必需
"openai-beta.realtime-v1"
]
);
ws.on("open", function open() {
console.log("Connected to server.");
});
ws.on("message", function incoming(message) {
console.log(message.data);
});
```
#### 消息收发示例 [#消息收发示例]
##### Node.js/浏览器 [#nodejs浏览器]
```javascript
// 接收服务器事件
ws.on("message", function incoming(message) {
// 需要从JSON解析消息数据
const serverEvent = JSON.parse(message.data)
console.log(serverEvent);
});
// 发送事件，创建符合客户端事件格式的JSON数据结构
const event = {
type: "response.create",
response: {
modalities: ["audio", "text"],
instructions: "Give me a haiku about code.",
}
};
ws.send(JSON.stringify(event));
```
##### Python [#python]
```python
# 发送客户端事件，将字典序列化为JSON
def on_open(ws):
print("Connected to server.")
event = {
"type": "response.create",
"response": {
"modalities": ["text"],
"instructions": "Please assist the user."
}
}
ws.send(json.dumps(event))
# 接收消息需要从JSON解析消息负载
def on_message(ws, message):
data = json.loads(message)
print("Received event:", json.dumps(data, indent=2))
```
## ⚠️ 错误处理 [#️-错误处理]
### 常见错误 [#常见错误]
1. 连接错误
* 网络问题
* 认证失败
* 配置错误
2. 音频错误
* 设备权限
* 格式不支持
* 编解码问题
3. 会话错误
* 令牌过期
* 会话超时
* 并发限制
### 错误恢复 [#错误恢复]
1. 自动重连
2. 会话恢复
3. 错误重试
4. 降级处理
## 📝 事件参考 [#-事件参考]
### 通用请求头 [#通用请求头]
所有事件都需要包含以下请求头:
| 请求头 | 类型 | 说明 | 示例值 |
| ------------- | --- | ------ | ---------------- |
| Authorization | 字符串 | 认证令牌 | Bearer $API\_KEY |
| OpenAI-Beta | 字符串 | API 版本 | realtime=v1 |
### 客户端事件 [#客户端事件]
#### session.update [#sessionupdate]
更新会话的默认配置。
| 参数 | 类型 | 必需 | 说明 | 示例值/可选值 |
| ------------------------------------- | ------ | -- | ----------------- | ------------------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_123 |
| type | 字符串 | 否 | 事件类型 | session.update |
| modalities | 字符串数组 | 否 | 模型可以响应的模态类型 | \["text", "audio"] |
| instructions | 字符串 | 否 | 预置到模型调用前的系统指令 | "Your knowledge cutoff is 2023-10..." |
| voice | 字符串 | 否 | 模型使用的语音类型 | alloy、echo、shimmer |
| input\_audio\_format | 字符串 | 否 | 输入音频格式 | pcm16、g711\_ulaw、g711\_alaw |
| output\_audio\_format | 字符串 | 否 | 输出音频格式 | pcm16、g711\_ulaw、g711\_alaw |
| input\_audio\_transcription.model | 字符串 | 否 | 用于转写的模型 | whisper-1 |
| turn\_detection.type | 字符串 | 否 | 语音检测类型 | server\_vad |
| turn\_detection.threshold | 数字 | 否 | VAD 激活阈值(0.0-1.0) | 0.8 |
| turn\_detection.prefix\_padding\_ms | 整数 | 否 | 语音开始前包含的音频时长 | 500 |
| turn\_detection.silence\_duration\_ms | 整数 | 否 | 检测语音停止的静音持续时间 | 1000 |
| tools | 数组 | 否 | 模型可用的工具列表 | \[] |
| tool\_choice | 字符串 | 否 | 模型选择工具的方式 | auto/none/required |
| temperature | 数字 | 否 | 模型采样温度 | 0.8 |
| max\_output\_tokens | 字符串/整数 | 否 | 单次响应最大token数 | "inf"/4096 |
#### input\_audio\_buffer.append [#input_audio_bufferappend]
向输入音频缓冲区追加音频数据。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ------------- | --------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_456 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.append |
| audio | 字符串 | 否 | Base64编码的音频数据 | Base64EncodedAudioData |
#### input\_audio\_buffer.commit [#input_audio_buffercommit]
将缓冲区中的音频数据提交为用户消息。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | --------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_789 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.commit |
#### input\_audio\_buffer.clear [#input_audio_bufferclear]
清空输入音频缓冲区中的所有音频数据。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | -------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_012 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.clear |
#### conversation.item.create [#conversationitemcreate]
向对话中添加新的对话项。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------------ | --- | -- | ------------- | --------------------------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_345 |
| type | 字符串 | 否 | 事件类型 | conversation.item.create |
| previous\_item\_id | 字符串 | 否 | 新对话项将插入在此ID之后 | null |
| item.id | 字符串 | 否 | 对话项的唯一标识符 | msg\_001 |
| item.type | 字符串 | 否 | 对话项类型 | message/function\_call/function\_call\_output |
| item.status | 字符串 | 否 | 对话项状态 | completed/in\_progress/incomplete |
| item.role | 字符串 | 否 | 消息发送者的角色 | user/assistant/system |
| item.content | 数组 | 否 | 消息内容 | \[text/audio/transcript] |
| item.call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| item.name | 字符串 | 否 | 被调用的函数名称 | function\_name |
| item.arguments | 字符串 | 否 | 函数调用的参数 | \{"param": "value"} |
| item.output | 字符串 | 否 | 函数调用的输出结果 | \{"result": "value"} |
#### conversation.item.truncate [#conversationitemtruncate]
截断助手消息中的音频内容。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ------------ | -------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_678 |
| type | 字符串 | 否 | 事件类型 | conversation.item.truncate |
| item\_id | 字符串 | 否 | 要截断的助手消息项的ID | msg\_002 |
| content\_index | 整数 | 否 | 要截断的内容部分的索引 | 0 |
| audio\_end\_ms | 整数 | 否 | 音频截断的结束时间点 | 1500 |
#### conversation.item.delete [#conversationitemdelete]
从对话历史中删除指定的对话项。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | ------------------------ |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_901 |
| type | 字符串 | 否 | 事件类型 | conversation.item.delete |
| item\_id | 字符串 | 否 | 要删除的对话项的ID | msg\_003 |
#### response.create [#responsecreate]
触发响应生成。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------------------------ | ------ | -- | ----------- | -------------------------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_234 |
| type | 字符串 | 否 | 事件类型 | response.create |
| response.modalities | 字符串数组 | 否 | 响应的模态类型 | \["text", "audio"] |
| response.instructions | 字符串 | 否 | 给模型的指令 | "Please assist the user." |
| response.voice | 字符串 | 否 | 模型使用的语音类型 | alloy/echo/shimmer |
| response.output\_audio\_format | 字符串 | 否 | 输出音频格式 | pcm16 |
| response.tools | 数组 | 否 | 模型可用的工具列表 | \["type", "name", "description"] |
| response.tool\_choice | 字符串 | 否 | 模型选择工具的方式 | auto |
| response.temperature | 数字 | 否 | 采样温度 | 0.7 |
| response.max\_output\_tokens | 整数/字符串 | 否 | 最大输出token数 | 150/"inf" |
#### response.cancel [#responsecancel]
取消正在进行中的响应生成。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | --------------- |
| event\_id | 字符串 | 否 | 客户端生成的事件标识符 | event\_567 |
| type | 字符串 | 否 | 事件类型 | response.cancel |
### 服务端事件 [#服务端事件]
#### error [#error]
当发生错误时返回的事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------------- | ----- | -- | ----------- | ------------------------------------- |
| event\_id | 字符串数组 | 否 | 服务端事件的唯一标识符 | \["event\_890"] |
| type | 字符串 | 否 | 事件类型 | error |
| error.type | 字符串 | 否 | 错误类型 | invalid\_request\_error/server\_error |
| error.code | 字符串 | 否 | 错误代码 | invalid\_event |
| error.message | 字符串 | 否 | 人类可读的错误消息 | "The 'type' field is missing." |
| error.param | 字符串 | 否 | 与错误相关的参数 | null |
| error.event\_id | 字符串 | 否 | 相关事件的ID | event\_567 |
#### conversation.item.input\_audio\_transcription.completed [#conversationiteminput_audio_transcriptioncompleted]
当启用输入音频转写功能并且转写成功时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ------------ | ------------------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2122 |
| type | 字符串 | 否 | 事件类型 | conversation.item.input\_audio\_transcription.completed |
| item\_id | 字符串 | 否 | 用户消息项的ID | msg\_003 |
| content\_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 |
| transcript | 字符串 | 否 | 转写的文本内容 | "Hello, how are you?" |
#### conversation.item.input\_audio\_transcription.failed [#conversationiteminput_audio_transcriptionfailed]
当配置了输入音频转写功能,但用户消息的转写请求失败时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | ----- | -- | ------------ | --------------------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2324 |
| type | 字符串数组 | 否 | 事件类型 | \["conversation.item.input\_audio\_transcription.failed"] |
| item\_id | 字符串 | 否 | 用户消息项的ID | msg\_003 |
| content\_index | 整数 | 否 | 包含音频的内容部分的索引 | 0 |
| error.type | 字符串 | 否 | 错误类型 | transcription\_error |
| error.code | 字符串 | 否 | 错误代码 | audio\_unintelligible |
| error.message | 字符串 | 否 | 人类可读的错误消息 | "The audio could not be transcribed." |
| error.param | 字符串 | 否 | 与错误相关的参数 | null |
#### conversation.item.truncated [#conversationitemtruncated]
当客户端截断了之前的助手音频消息项时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ------------- | --------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2526 |
| type | 字符串 | 否 | 事件类型 | conversation.item.truncated |
| item\_id | 字符串 | 否 | 被截断的助手消息项的ID | msg\_004 |
| content\_index | 整数 | 否 | 被截断的内容部分的索引 | 0 |
| audio\_end\_ms | 整数 | 否 | 音频被截断的时间点(毫秒) | 1500 |
#### conversation.item.deleted [#conversationitemdeleted]
当对话中的某个项目被删除时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | ------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2728 |
| type | 字符串 | 否 | 事件类型 | conversation.item.deleted |
| item\_id | 字符串 | 否 | 被删除的对话项的ID | msg\_005 |
#### input\_audio\_buffer.committed [#input_audio_buffercommitted]
当音频缓冲区中的数据被提交时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------------ | --- | -- | ------------------- | ------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1121 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.committed |
| previous\_item\_id | 字符串 | 否 | 新对话项将插入在此ID对应的对话项之后 | msg\_001 |
| item\_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg\_002 |
#### input\_audio\_buffer.cleared [#input_audio_buffercleared]
当客户端清空输入音频缓冲区时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | ---------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1314 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.cleared |
#### input\_audio\_buffer.speech\_started [#input_audio_bufferspeech_started]
在服务器语音检测模式下，当检测到语音输入时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ---------------- | --- | -- | ----------------- | ------------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1516 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.speech\_started |
| audio\_start\_ms | 整数 | 否 | 从会话开始到检测到语音的毫秒数 | 1000 |
| item\_id | 字符串 | 否 | 语音停止时将创建的用户消息项的ID | msg\_003 |
#### input\_audio\_buffer.speech\_stopped [#input_audio_bufferspeech_stopped]
在服务器语音检测模式下，当检测到语音输入停止时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ---------------- | --- | -- | ----------------- | ------------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1718 |
| type | 字符串 | 否 | 事件类型 | input\_audio\_buffer.speech\_stopped |
| audio\_start\_ms | 整数 | 否 | 从会话开始到检测到语音停止的毫秒数 | 2000 |
| item\_id | 字符串 | 否 | 将要创建的用户消息项的ID | msg\_003 |
#### response.created [#responsecreated]
当创建新的响应时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------------------ | ----- | -- | ----------- | ----------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_2930 |
| type | 字符串 | 否 | 事件类型 | response.created |
| response.id | 字符串 | 否 | 响应的唯一标识符 | resp\_001 |
| response.object | 字符串 | 否 | 对象类型 | realtime.response |
| response.status | 字符串 | 否 | 响应的状态 | in\_progress |
| response.status\_details | 对象 | 否 | 状态的附加详细信息 | null |
| response.output | 字符串数组 | 否 | 响应生成的输出项列表 | \["\[]"] |
| response.usage | 对象 | 否 | 响应的使用统计信息 | null |
#### response.done [#responsedone]
当响应完成流式传输时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ----------------------------- | ----- | -- | ----------- | ------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3132 |
| type | 字符串 | 否 | 事件类型 | response.done |
| response.id | 字符串 | 否 | 响应的唯一标识符 | resp\_001 |
| response.object | 字符串 | 否 | 对象类型 | realtime.response |
| response.status | 字符串 | 否 | 响应的最终状态 | completed/cancelled/failed/incomplete |
| response.status\_details | 对象 | 否 | 状态的附加详细信息 | null |
| response.output | 字符串数组 | 否 | 响应生成的输出项列表 | \["\[...]"] |
| response.usage.total\_tokens | 整数 | 否 | 总token数 | 50 |
| response.usage.input\_tokens | 整数 | 否 | 输入token数 | 20 |
| response.usage.output\_tokens | 整数 | 否 | 输出token数 | 30 |
#### response.output\_item.added [#responseoutput_itemadded]
当响应生成过程中创建新的输出项时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------- | --- | -- | ----------- | --------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3334 |
| type | 字符串 | 否 | 事件类型 | response.output\_item.added |
| response\_id | 字符串 | 否 | 输出项所属的响应ID | resp\_001 |
| output\_index | 字符串 | 否 | 输出项在响应中的索引 | 0 |
| item.id | 字符串 | 否 | 输出项的唯一标识符 | msg\_007 |
| item.object | 字符串 | 否 | 对象类型 | realtime.item |
| item.type | 字符串 | 否 | 输出项类型 | message/function\_call/function\_call\_output |
| item.status | 字符串 | 否 | 输出项状态 | in\_progress/completed |
| item.role | 字符串 | 否 | 与输出项关联的角色 | assistant |
| item.content | 数组 | 否 | 输出项的内容 | \["type", "text", "audio", "transcript"] |
#### response.output\_item.done [#responseoutput_itemdone]
当输出项完成流式传输时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------- | --- | -- | ----------- | --------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3536 |
| type | 字符串 | 否 | 事件类型 | response.output\_item.done |
| response\_id | 字符串 | 否 | 输出项所属的响应ID | resp\_001 |
| output\_index | 字符串 | 否 | 输出项在响应中的索引 | 0 |
| item.id | 字符串 | 否 | 输出项的唯一标识符 | msg\_007 |
| item.object | 字符串 | 否 | 对象类型 | realtime.item |
| item.type | 字符串 | 否 | 输出项类型 | message/function\_call/function\_call\_output |
| item.status | 字符串 | 否 | 输出项的最终状态 | completed/incomplete |
| item.role | 字符串 | 否 | 与输出项关联的角色 | assistant |
| item.content | 数组 | 否 | 输出项的内容 | \["type", "text", "audio", "transcript"] |
#### response.content\_part.added [#responsecontent_partadded]
当响应生成过程中向助手消息项添加新的内容部分时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------------- | --- | -- | ---------------- | ------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3738 |
| type | 字符串 | 否 | 事件类型 | response.content\_part.added |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 添加内容部分的消息项ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| part.type | 字符串 | 否 | 内容类型 | text/audio |
| part.text | 字符串 | 否 | 文本内容 | "Hello" |
| part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64\_encoded\_audio\_data" |
| part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" |
#### response.content\_part.done [#responsecontent_partdone]
当助手消息项中的内容部分完成流式传输时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------------- | --- | -- | ---------------- | ------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_3940 |
| type | 字符串 | 否 | 事件类型 | response.content\_part.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 添加内容部分的消息项ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| part.type | 字符串 | 否 | 内容类型 | text/audio |
| part.text | 字符串 | 否 | 文本内容 | "Hello" |
| part.audio | 字符串 | 否 | Base64编码的音频数据 | "base64\_encoded\_audio\_data" |
| part.transcript | 字符串 | 否 | 音频的转写文本 | "Hello" |
#### response.text.delta [#responsetextdelta]
当"text"类型内容部分的文本值更新时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | ------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4142 |
| type | 字符串 | 否 | 事件类型 | response.text.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 文本增量更新内容 | "Sure, I can h" |
#### response.text.done [#responsetextdone]
当"text"类型内容部分的文本流式传输完成时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | ----------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4344 |
| type | 字符串 | 否 | 事件类型 | response.text.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_007 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 最终的完整文本内容 | "Sure, I can help with that." |
#### response.audio\_transcript.delta [#responseaudio_transcriptdelta]
当模型生成的音频输出转写内容更新时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | -------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4546 |
| type | 字符串 | 否 | 事件类型 | response.audio\_transcript.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | 转写文本的增量更新内容 | "Hello, how can I a" |
#### response.audio\_transcript.done [#responseaudio_transcriptdone]
当模型生成的音频输出转写完成流式传输时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | ------------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4748 |
| type | 字符串 | 否 | 事件类型 | response.audio\_transcript.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| transcript | 字符串 | 否 | 音频的最终完整转写文本 | "Hello, how can I assist you today?" |
#### response.audio.delta [#responseaudiodelta]
当模型生成的音频内容更新时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | ------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_4950 |
| type | 字符串 | 否 | 事件类型 | response.audio.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
| delta | 字符串 | 否 | Base64编码的音频数据增量 | "Base64EncodedAudioDelta" |
#### response.audio.done [#responseaudiodone]
当模型生成的音频完成时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ---------------- | ------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5152 |
| type | 字符串 | 否 | 事件类型 | response.audio.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_001 |
| item\_id | 字符串 | 否 | 消息项的ID | msg\_008 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| content\_index | 整数 | 否 | 内容部分在消息项内容数组中的索引 | 0 |
### 函数调用 [#函数调用]
#### response.function\_call\_arguments.delta [#responsefunction_call_argumentsdelta]
当模型生成的函数调用参数更新时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------- | --- | -- | --------------- | ---------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5354 |
| type | 字符串 | 否 | 事件类型 | response.function\_call\_arguments.delta |
| response\_id | 字符串 | 否 | 响应的ID | resp\_002 |
| item\_id | 字符串 | 否 | 消息项的ID | fc\_001 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| delta | 字符串 | 否 | JSON格式的函数调用参数增量 | "\{"location": "San"" |
#### response.function\_call\_arguments.done [#responsefunction_call_argumentsdone]
当模型生成的函数调用参数完成流式传输时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------- | --- | -- | ------------------- | --------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5556 |
| type | 字符串 | 否 | 事件类型 | response.function\_call\_arguments.done |
| response\_id | 字符串 | 否 | 响应的ID | resp\_002 |
| item\_id | 字符串 | 否 | 消息项的ID | fc\_001 |
| output\_index | 整数 | 否 | 输出项在响应中的索引 | 0 |
| call\_id | 字符串 | 否 | 函数调用的ID | call\_001 |
| arguments | 字符串 | 否 | 最终的完整函数调用参数(JSON格式) | "\{"location": "San Francisco"}" |
### 其他状态更新 [#其他状态更新]
#### rate\_limits.updated [#rate_limitsupdated]
在每个 "response.done" 事件之后触发,用于指示更新后的速率限制。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------ | ---- | -- | ----------- | -------------------------------------------------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5758 |
| type | 字符串 | 否 | 事件类型 | rate\_limits.updated |
| rate\_limits | 对象数组 | 否 | 速率限制信息列表 | \[\{"name": "requests\_per\_min", "limit": 60, "remaining": 45, "reset\_seconds": 35}] |
#### conversation.created [#conversationcreated]
当对话创建时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------ | --- | -- | ----------- | ------------------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_9101 |
| type | 字符串 | 否 | 事件类型 | conversation.created |
| conversation | 对象 | 否 | 对话资源对象 | \{"id": "conv\_001", "object": "realtime.conversation"} |
#### conversation.item.created [#conversationitemcreated]
当对话项创建时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ------------------ | --- | -- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1920 |
| type | 字符串 | 否 | 事件类型 | conversation.item.created |
| previous\_item\_id | 字符串 | 否 | 前一个对话项的ID | msg\_002 |
| item | 对象 | 否 | 对话项对象 | \{"id": "msg\_003", "object": "realtime.item", "type": "message", "status": "completed", "role": "user", "content": \[\{"type": "text", "text": "Hello"}]} |
#### session.created [#sessioncreated]
当会话创建时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | ------------------------------------------------------------------------------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_1234 |
| type | 字符串 | 否 | 事件类型 | session.created |
| session | 对象 | 否 | 会话对象 | \{"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": \["text", "audio"]} |
#### session.updated [#sessionupdated]
当会话更新时返回此事件。
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ----------- | ------------------------------------------------------------------------------------------------------ |
| event\_id | 字符串 | 否 | 服务端事件的唯一标识符 | event\_5678 |
| type | 字符串 | 否 | 事件类型 | session.updated |
| session | 对象 | 否 | 更新后的会话对象 | \{"id": "sess\_001", "object": "realtime.session", "model": "gpt-4", "modalities": \["text", "audio"]} |
### 速率限制事件参数表 [#速率限制事件参数表]
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| -------------- | --- | -- | ------- | ------------------ |
| name | 字符串 | 是 | 限制名称 | requests\_per\_min |
| limit | 整数 | 是 | 限制值 | 60 |
| remaining | 整数 | 是 | 剩余可用量 | 45 |
| reset\_seconds | 整数 | 是 | 重置时间(秒) | 35 |
### 函数调用参数表 [#函数调用参数表]
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| ----------- | --- | -- | ------ | ----------------------------------------- |
| type | 字符串 | 是 | 函数类型 | function |
| name | 字符串 | 是 | 函数名称 | get\_weather |
| description | 字符串 | 否 | 函数描述 | Get the current weather |
| parameters | 对象 | 是 | 函数参数定义 | \{"type": "object", "properties": \{...}} |
### 音频格式参数表 [#音频格式参数表]
| 参数 | 类型 | 说明 | 可选值 |
| ----------------- | --- | ---- | -------------------------------- |
| sample\_rate | 整数 | 采样率 | 8000, 16000, 24000, 44100, 48000 |
| channels | 整数 | 声道数 | 1 (单声道), 2 (立体声) |
| bits\_per\_sample | 整数 | 采样位数 | 16 (pcm16), 8 (g711) |
| encoding | 字符串 | 编码方式 | pcm16, g711\_ulaw, g711\_alaw |
### 语音检测参数表 [#语音检测参数表]
| 参数 | 类型 | 说明 | 默认值 | 范围 |
| --------------------- | --- | ---------- | ---- | --------- |
| threshold | 浮点数 | VAD 激活阈值 | 0.5 | 0.0-1.0 |
| prefix\_padding\_ms | 整数 | 语音前缀填充(毫秒) | 500 | 0-5000 |
| silence\_duration\_ms | 整数 | 静音检测时长(毫秒) | 1000 | 100-10000 |
### 工具选择参数表 [#工具选择参数表]
| 参数 | 类型 | 说明 | 可选值 |
| ------------ | --- | ------ | ----------------------------------------- |
| tool\_choice | 字符串 | 工具选择方式 | auto, none, required |
| tools | 数组 | 可用工具列表 | \[\{type, name, description, parameters}] |
### 模型配置参数表 [#模型配置参数表]
| 参数 | 类型 | 说明 | 范围/可选值 | 默认值 |
| ------------------- | ------ | ------ | -------------------- | --------- |
| temperature | 浮点数 | 采样温度 | 0.0-2.0 | 1.0 |
| max\_output\_tokens | 整数/字符串 | 最大输出长度 | 1-4096/"inf" | "inf" |
| modalities | 字符串数组 | 响应模态 | \["text", "audio"] | \["text"] |
| voice | 字符串 | 语音类型 | alloy, echo, shimmer | alloy |
### 事件通用参数表 [#事件通用参数表]
| 参数 | 类型 | 必需 | 说明 | 示例值 |
| --------- | --- | -- | ------------ | -------------- |
| event\_id | 字符串 | 是 | 事件的唯一标识符 | event\_123 |
| type | 字符串 | 是 | 事件类型 | session.update |
| timestamp | 整数 | 否 | 事件发生的时间戳(毫秒) | 1677649363000 |
### 会话状态参数表 [#会话状态参数表]
| 参数 | 类型 | 说明 | 可选值 |
| -------- | --- | ----- | ---------------------------------------------------- |
| status | 字符串 | 会话状态 | active, ended, error |
| error | 对象 | 错误信息 | \{"type": "error\_type", "message": "error message"} |
| metadata | 对象 | 会话元数据 | \{"client\_id": "web", "session\_type": "chat"} |
### 对话项状态参数表 [#对话项状态参数表]
| 参数 | 类型 | 说明 | 可选值 |
| ------ | --- | ----- | ----------------------------------------------- |
| status | 字符串 | 对话项状态 | completed, in\_progress, incomplete |
| role | 字符串 | 发送者角色 | user, assistant, system |
| type | 字符串 | 对话项类型 | message, function\_call, function\_call\_output |
### 内容类型参数表 [#内容类型参数表]
| 参数 | 类型 | 说明 | 可选值 |
| -------- | --- | ---- | ----------------------- |
| type | 字符串 | 内容类型 | text, audio, transcript |
| format | 字符串 | 内容格式 | plain, markdown, html |
| encoding | 字符串 | 编码方式 | utf-8, base64 |
### 响应状态参数表 [#响应状态参数表]
| 参数 | 类型 | 说明 | 可选值 |
| --------------- | --- | ---- | ----------------------------------------------------------------- |
| status | 字符串 | 响应状态 | completed, cancelled, failed, incomplete |
| status\_details | 对象 | 状态详情 | \{"reason": "user\_cancelled"} |
| usage | 对象 | 使用统计 | \{"total\_tokens": 50, "input\_tokens": 20, "output\_tokens": 30} |
### 音频转写参数表 [#音频转写参数表]
| 参数 | 类型 | 说明 | 示例值 |
| -------- | --- | ------ | ------------------------------ |
| enabled | 布尔值 | 是否启用转写 | true |
| model | 字符串 | 转写模型 | whisper-1 |
| language | 字符串 | 转写语言 | en, zh, auto |
| prompt | 字符串 | 转写提示词 | "Transcript of a conversation" |
### 音频流参数表 [#音频流参数表]
| 参数 | 类型 | 说明 | 可选值 |
| ----------- | --- | --------- | ------------------- |
| chunk\_size | 整数 | 音频块大小(字节) | 1024, 2048, 4096 |
| latency | 字符串 | 延迟模式 | low, balanced, high |
| compression | 字符串 | 压缩方式 | none, opus, mp3 |
### WebRTC 配置参数表 [#webrtc-配置参数表]
| 参数 | 类型 | 说明 | 默认值 |
| ------------------- | -- | --------- | -------------------------------------------- |
| ice\_servers | 数组 | ICE 服务器列表 | \[\{"urls": "stun:stun.l.google.com:19302"}] |
| audio\_constraints | 对象 | 音频约束 | \{"echoCancellation": true} |
| connection\_timeout | 整数 | 连接超时(毫秒) | 30000 |
# OpenAI 响应格式（Responses） (/zh/api/openai-responses)
[OpenAI Responses](https://platform.openai.com/docs/api-reference/responses)
## 📝 简介 [#-简介]
OpenAI 最先进的模型响应接口。支持文本和图像输入，以及文本输出。创建与模型的有状态交互，将先前响应的输出用作输入。通过文件搜索、网络搜索、计算机使用等内置工具扩展模型的能力。使用函数调用允许模型访问外部系统和数据。
相关指南可参阅OpenAI官网：[Responses](https://platform.openai.com/docs/guides/migrate-to-responses)
## 💡 请求示例 [#-请求示例]
### 基础文本响应 ✅ [#基础文本响应-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "讲一个三句话的关于独角兽的睡前故事。"
}'
```
**响应示例:**
```json
{
"id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
"object": "response",
"created_at": 1741476542,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "在一个宁静的月夜下，一只名叫璐米娜的独角兽发现了一个倒映着星星的隐藏水池。当她将独角浸入水中时，水池开始闪烁，显现出通往一个有着无尽夜空的魔法世界的路径。充满好奇，璐米娜为所有做梦的人许下愿望，希望他们能找到自己的隐藏魔法，当她回头望去，她的蹄印像星尘一样闪烁。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 36,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 87,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 123
},
"user": null,
"metadata": {}
}
```
### 图像分析响应 ✅ [#图像分析响应-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "描述这张图片中的内容"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
}
]
}
]
}'
```
**响应示例:**
```json
{
"id": "resp_67ccd3a9da748190baa7f1570fe91ac604becb25c45c1d41",
"object": "response",
"created_at": 1741476777,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "message",
"id": "msg_67ccd3acc8d48190a77525dc6de64b4104becb25c45c1d41",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "这张图片展示了一条木制栈道或小径穿过茂密的绿色草地，上方是点缀着几朵云的蓝天。场景呈现出一个宁静的自然区域，可能是公园或自然保护区。背景中有树木和灌木丛。整个景观展现出和谐的自然环境，栈道为游客提供了一条穿过湿地或草原而不影响周围生态系统的路径。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 52,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 380
},
"user": null,
"metadata": {}
}
```
### 网络搜索工具 ✅ [#网络搜索工具-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{ "type": "web_search_preview" }],
"input": "今天有什么积极正面的新闻?"
}'
```
**响应示例:**
```json
{
"id": "resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c",
"object": "response",
"created_at": 1741484430,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "web_search_call",
"id": "ws_67ccf18f64008190a39b619f4c8455ef087bb177ab789d5c",
"status": "completed"
},
{
"type": "message",
"id": "msg_67ccf190ca3881909d433c50b1f6357e087bb177ab789d5c",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "截至今天，2025年3月9日，一则值得关注的积极新闻是中国科学家在可再生能源领域取得重大突破，成功研发出一种新型高效太阳能电池，转化率达到了创纪录的35%，这可能会极大推动清洁能源的普及和应用。这项技术预计将使太阳能发电成本降低约40%，为全球减少碳排放提供了新的解决方案。",
"annotations": [
{
"type": "url_citation",
"start_index": 42,
"end_index": 100,
"url": "https://example.com/renewable-energy-breakthrough/?utm_source=chatgpt.com",
"title": "中国科学家在可再生能源领域取得重大突破"
},
{
"type": "url_citation",
"start_index": 101,
"end_index": 150,
"url": "https://example.com/solar-cell-efficiency-record/?utm_source=chatgpt.com",
"title": "新型高效太阳能电池转化率创纪录"
},
{
"type": "url_citation",
"start_index": 151,
"end_index": 200,
"url": "https://example.com/clean-energy-cost-reduction/?utm_source=chatgpt.com",
"title": "太阳能发电成本有望降低40%"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "web_search_preview",
"domains": [],
"search_context_size": "medium",
"user_location": {
"type": "approximate",
"city": null,
"country": "US",
"region": null,
"timezone": null
}
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 328,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 356,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 684
},
"user": null,
"metadata": {}
}
```
### 文件搜索工具 ✅ [#文件搜索工具-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"tools": [{
"type": "file_search",
"vector_store_ids": ["vs_1234567890"],
"max_num_results": 20
}],
"input": "古代棕龙有哪些特性和属性?"
}'
```
**响应示例:**
```json
{
"id": "resp_67ccf4c55fc48190b71bd0463ad3306d09504fb6872380d7",
"object": "response",
"created_at": 1741485253,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1",
"output": [
{
"type": "file_search_call",
"id": "fs_67ccf4c63cd08190887ef6464ba5681609504fb6872380d7",
"status": "completed",
"queries": [
"古代棕龙的特性和属性"
],
"results": null
},
{
"type": "message",
"id": "msg_67ccf4c93e5c81909d595b369351a9d309504fb6872380d7",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "根据资料，古代棕龙具有以下特性和属性：\n\n1. 物理特征：古代棕龙体型庞大，体长可达25-30米，翼展约35米。它们的鳞片呈深棕色至铜色，随着年龄增长会变得更加暗沉。头部有特征性的双角和脊刺，下颚强壮，适合撕裂猎物。\n\n2. 能力：它们能喷吐强力的酸液，对目标造成严重腐蚀伤害。古代棕龙还拥有出色的掘地能力，常在沙漠或山地挖掘复杂的巢穴系统。\n\n3. 智力：被认为是龙族中最为狡猾和有耐心的品种，智力极高，精通多种语言，并具有复杂的战术思维。\n\n4. 栖息地：主要栖息在干旱的山地和沙漠地区，喜欢炎热干燥的环境。\n\n5. 宝藏：古代棕龙以其庞大的宝藏闻名，特别喜爱收集铜币、红宝石和火焰魔法物品。\n\n6. 寿命：是所有龙种中寿命最长的之一，可活2000-2500年，随着年龄增长其力量和魔法能力也会增强。\n\n7. 性格：极度领地意识强，性格暴躁易怒，对侵入者毫不留情，但也以其罕见的耐心著称，能为复仇等待几个世纪。",
"annotations": [
{
"type": "file_citation",
"index": 80,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 233,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 345,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 420,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 520,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 580,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 655,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
},
{
"type": "file_citation",
"index": 781,
"file_id": "file-4wDz5b167pAf72nx1h9eiN",
"filename": "dragons.pdf"
}
]
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "file_search",
"filters": null,
"max_num_results": 20,
"ranking_options": {
"ranker": "auto",
"score_threshold": 0.0
},
"vector_store_ids": [
"vs_1234567890"
]
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 18307,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 348,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 18655
},
"user": null,
"metadata": {}
}
```
### 流式响应 ✅ [#流式响应-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"instructions": "你是一个有帮助的助手。",
"input": "你好！",
"stream": true
}'
```
**流式响应示例:**
```
event: response.created
data: {"type":"response.created","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":null,"user":null,"metadata":{}}}
event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"in_progress","role":"assistant","content":[]}}
event: response.content_part.added
data: {"type":"response.content_part.added","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"你好"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"！"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":" 我"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"能"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"为"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"您"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"提供"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"什么"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"帮助"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"吗"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"？"}
event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"text":"你好！ 我能为您提供什么帮助吗？"}
event: response.content_part.done
data: {"type":"response.content_part.done","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"part":{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}}
event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_67c9fdcecf488190bdd9a0409de3a1ec07b8b0ad4e5eb654","object":"response","created_at":1741290958,"status":"completed","error":null,"incomplete_details":null,"instructions":"你是一个有帮助的助手。","max_output_tokens":null,"model":"gpt-4.1-2025-04-14","output":[{"id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！ 我能为您提供什么帮助吗？","annotations":[]}]}],"parallel_tool_calls":true,"previous_response_id":null,"reasoning":{"effort":null,"summary":null},"store":true,"temperature":1.0,"text":{"format":{"type":"text"}},"tool_choice":"auto","tools":[],"top_p":1.0,"truncation":"disabled","usage":{"input_tokens":37,"output_tokens":11,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":48},"user":null,"metadata":{}}}
```
### 函数调用 ✅ [#函数调用-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "gpt-4.1",
"input": "波士顿今天的天气如何？",
"tools": [
{
"type": "function",
"name": "get_current_weather",
"description": "获取指定位置的当前天气",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location", "unit"]
}
}
],
"tool_choice": "auto"
}'
```
**响应示例:**
```json
{
"id": "resp_67ca09c5efe0819096d0511c92b8c890096610f474011cc0",
"object": "response",
"created_at": 1741294021,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "gpt-4.1-2025-04-14",
"output": [
{
"type": "function_call",
"id": "fc_67ca09c6bedc8190a7abfec07b1a1332096610f474011cc0",
"call_id": "call_unLAR8MvFNptuiZK6K6HCy5k",
"name": "get_current_weather",
"arguments": "{\"location\":\"波士顿, MA\",\"unit\":\"celsius\"}",
"status": "completed"
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": null,
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "function",
"description": "获取指定位置的当前天气",
"name": "get_current_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市和州，例如 San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"unit"
]
},
"strict": true
}
],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 291,
"output_tokens": 23,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 314
},
"user": null,
"metadata": {}
}
```
### 推理能力 ✅ [#推理能力-]
```bash
curl https://api.zipflow.xyz/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-d '{
"model": "o3-mini",
"input": "一只啄木鸟能啄多少木头?",
"reasoning": {
"effort": "high"
}
}'
```
**响应示例:**
```json
{
"id": "resp_67ccd7eca01881908ff0b5146584e408072912b2993db808",
"object": "response",
"created_at": 1741477868,
"status": "completed",
"error": null,
"incomplete_details": null,
"instructions": null,
"max_output_tokens": null,
"model": "o1-2024-12-17",
"output": [
{
"type": "message",
"id": "msg_67ccd7f7b5848190a6f3e95d809f6b44072912b2993db808",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "这是一个源自英文绕口令"How much wood would a woodchuck chuck if a woodchuck could chuck wood"的问题。在现实中，啄木鸟(woodpecker)和土拨鼠(woodchuck)是不同的动物，而且土拨鼠实际上并不"啄(chuck)"木头。\n\n从科学角度看，啄木鸟每天确实会啄树木以寻找食物、建造巢穴或进行通讯。一只啄木鸟平均每天可能啄树约8000-12000次，视物种和具体目的而定。如果我们将这转换为木材量，假设每次啄击移除约0.1-0.2立方厘米的木材，那么一只啄木鸟理论上每天可能移除约800-2400立方厘米的木材。\n\n然而，啄木鸟主要是为了觅食和筑巢而啄木，而不是单纯地移除木材，所以这个计算只是一个有趣的理论估算。",
"annotations": []
}
]
}
],
"parallel_tool_calls": true,
"previous_response_id": null,
"reasoning": {
"effort": "high",
"summary": null
},
"store": true,
"temperature": 1.0,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [],
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 81,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 1035,
"output_tokens_details": {
"reasoning_tokens": 832
},
"total_tokens": 1116
},
"user": null,
"metadata": {}
}
```
## 📮 请求 [#-请求]
### 端点 [#端点]
```
POST /v1/responses
```
创建模型响应。提供文本或图像输入以生成文本或JSON输出。让模型调用您自己的自定义代码或使用内置工具（如网络搜索或文件搜索）将您自己的数据用作模型响应的输入。
### 鉴权方法 [#鉴权方法]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
其中 `$ZIPFLOW_API_KEY` 是您的 API 密钥。
### 请求体参数 [#请求体参数]
#### input [#input]
**类型**: 字符串或数组\
**必需**: 是
提供给模型的文本、图像或文件输入，用于生成响应。
##### 可能的类型 [#可能的类型]
| 类型 | 描述 |
| ----- | ------------------- |
| 字符串 | 文本输入，相当于具有用户角色的文本输入 |
| 输入项数组 | 包含不同内容类型的一个或多个输入项列表 |
##### 输入消息对象 [#输入消息对象]
| 属性 | 类型 | 必需 | 描述 |
| ------- | ------ | -- | ----------------------------------------------------- |
| content | 字符串或数组 | 是 | 提供给模型的文本、图像或音频输入，用于生成响应。也可以包含之前的助手响应 |
| role | 字符串 | 是 | 输入消息的角色。可选值：`user`、`assistant`、`system` 或 `developer` |
| type | 字符串 | 否 | 输入消息的类型，始终为 `message` |
##### 内容项类型 [#内容项类型]
###### 文本输入 [#文本输入]
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | ----------------------- |
| text | 字符串 | 是 | 提供给模型的文本输入 |
| type | 字符串 | 是 | 输入项的类型，始终为 `input_text` |
###### 图像输入 [#图像输入]
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | --------------------------------------------------- |
| detail | 字符串 | 是 | 要发送给模型的图像的详细级别。可选值：`high`、`low` 或 `auto`。默认为 `auto` |
| type | 字符串 | 是 | 输入项的类型，始终为 `input_image` |
| file\_id | 字符串 | 否 | 要发送给模型的文件ID |
| image\_url | 字符串 | 否 | 要发送给模型的图像URL。可以是完整的URL或数据URL中的base64编码图像 |
###### 文件输入 [#文件输入]
| 属性 | 类型 | 必需 | 描述 |
| ---------- | --- | -- | ----------------------- |
| type | 字符串 | 是 | 输入项的类型，始终为 `input_file` |
| file\_data | 字符串 | 否 | 要发送给模型的文件内容 |
| file\_id | 字符串 | 否 | 要发送给模型的文件ID |
| filename | 字符串 | 否 | 要发送给模型的文件名 |
##### 输出项类型 [#输出项类型]
###### 输出文本 [#输出文本]
| 属性 | 类型 | 必需 | 描述 |
| ----------- | --- | -- | ------------------------ |
| text | 字符串 | 是 | 模型生成的文本输出 |
| type | 字符串 | 是 | 输出项的类型，始终为 `output_text` |
| annotations | 数组 | 是 | 文本输出的注释 |
###### 注释类型 [#注释类型]
文件引用:
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | --------------------------- |
| file\_id | 字符串 | 是 | 文件的ID |
| index | 整数 | 是 | 文件在文件列表中的索引 |
| type | 字符串 | 是 | 文件引用的类型，始终为 `file_citation` |
URL引用:
| 属性 | 类型 | 必需 | 描述 |
| ------------ | --- | -- | --------------------------- |
| end\_index | 整数 | 是 | URL引用在消息中的最后一个字符的索引 |
| start\_index | 整数 | 是 | URL引用在消息中的第一个字符的索引 |
| title | 字符串 | 是 | 网络资源的标题 |
| type | 字符串 | 是 | URL引用的类型，始终为 `url_citation` |
| url | 字符串 | 是 | 网络资源的URL |
文件路径:
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | ----------------------- |
| file\_id | 字符串 | 是 | 文件的ID |
| index | 整数 | 是 | 文件在文件列表中的索引 |
| type | 字符串 | 是 | 文件路径的类型，始终为 `file_path` |
###### 拒绝响应 [#拒绝响应]
| 属性 | 类型 | 必需 | 描述 |
| ------- | --- | -- | ------------------- |
| refusal | 字符串 | 是 | 模型的拒绝解释 |
| type | 字符串 | 是 | 拒绝的类型，始终为 `refusal` |
##### 工具调用类型 [#工具调用类型]
###### 文件搜索工具调用 [#文件搜索工具调用]
| 属性 | 类型 | 必需 | 描述 |
| ------- | ------- | -- | ------------------------------------------------------------------- |
| id | 字符串 | 是 | 文件搜索工具调用的唯一ID |
| queries | 数组 | 是 | 用于搜索文件的查询 |
| status | 字符串 | 是 | 文件搜索工具调用的状态。可能值包括：`in_progress`、`searching`、`incomplete` 或 `failed` |
| type | 字符串 | 是 | 文件搜索工具调用的类型，始终为 `file_search_call` |
| results | 数组或null | 否 | 文件搜索工具调用的结果 |
###### 网络搜索工具调用 [#网络搜索工具调用]
| 属性 | 类型 | 必需 | 描述 |
| ------ | --- | -- | --------------------------------- |
| id | 字符串 | 是 | 网络搜索工具调用的唯一ID |
| status | 字符串 | 是 | 网络搜索工具调用的状态 |
| type | 字符串 | 是 | 网络搜索工具调用的类型，始终为 `web_search_call` |
###### 函数工具调用 [#函数工具调用]
| 属性 | 类型 | 必需 | 描述 |
| --------- | --- | -- | ------------------------------------------------ |
| arguments | 字符串 | 是 | 传递给函数的参数的JSON字符串 |
| call\_id | 字符串 | 是 | 模型生成的函数工具调用的唯一ID |
| name | 字符串 | 是 | 要运行的函数的名称 |
| type | 字符串 | 是 | 函数工具调用的类型，始终为 `function_call` |
| id | 字符串 | 否 | 函数工具调用的唯一ID |
| status | 字符串 | 否 | 项目的状态。可能值：`in_progress`、`completed`或`incomplete` |
###### 计算机工具调用 [#计算机工具调用]
| 属性 | 类型 | 必需 | 描述 |
| ----------------------- | --- | -- | ------------------------------------------------ |
| action | 对象 | 是 | 计算机交互的操作，如点击、拖拽等 |
| call\_id | 字符串 | 是 | 响应工具调用输出时使用的标识符 |
| id | 字符串 | 是 | 计算机调用的唯一ID |
| pending\_safety\_checks | 数组 | 是 | 计算机调用的待处理安全检查 |
| status | 字符串 | 是 | 项目的状态。可能值：`in_progress`、`completed`或`incomplete` |
| type | 字符串 | 是 | 计算机调用的类型，始终为 `computer_call` |
计算机操作类型:
| 操作类型 | 描述 |
| ------------- | ------ |
| click | 鼠标点击操作 |
| double\_click | 鼠标双击操作 |
| drag | 拖拽操作 |
| keypress | 按键操作 |
| move | 鼠标移动操作 |
| screenshot | 屏幕截图操作 |
| scroll | 滚动操作 |
| type | 文本输入操作 |
| wait | 等待操作 |
###### 计算机工具调用输出 [#计算机工具调用输出]
| 属性 | 类型 | 必需 | 描述 |
| ---------------------------- | --- | -- | -------------------------------------------------- |
| call\_id | 字符串 | 是 | 产生输出的计算机工具调用的ID |
| output | 对象 | 是 | 用于计算机使用工具的计算机屏幕截图图像 |
| type | 字符串 | 是 | 计算机工具调用输出的类型，始终为 `computer_call_output` |
| acknowledged\_safety\_checks | 数组 | 否 | API报告的已被开发者确认的安全检查 |
| id | 字符串 | 否 | 计算机工具调用输出的ID |
| status | 字符串 | 否 | 输入消息的状态。可能值：`in_progress`、`completed`或`incomplete` |
###### 函数工具调用输出 [#函数工具调用输出]
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | ------------------------------------------------ |
| call\_id | 字符串 | 是 | 模型生成的函数工具调用的唯一ID |
| output | 字符串 | 是 | 函数工具调用输出的JSON字符串 |
| type | 字符串 | 是 | 函数工具调用输出的类型，始终为 `function_call_output` |
| id | 字符串 | 否 | 函数工具调用输出的唯一ID |
| status | 字符串 | 否 | 项目的状态。可能值：`in_progress`、`completed`或`incomplete` |
##### 推理相关项 [#推理相关项]
| 属性 | 类型 | 必需 | 描述 |
| ------------------ | -------- | -- | -------------------------------------------------------- |
| id | 字符串 | 是 | 推理内容的唯一标识符 |
| summary | 数组 | 是 | 推理文本内容 |
| type | 字符串 | 是 | 对象的类型，始终为 `reasoning` |
| encrypted\_content | 字符串或null | 否 | 推理项的加密内容 - 当使用 `reasoning.encrypted_content` 包含参数生成响应时填充 |
| status | 字符串 | 否 | 项目的状态。可能值：`in_progress`、`completed`或`incomplete` |
推理摘要:
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | ------------------------ |
| text | 字符串 | 是 | 模型生成响应时使用的推理的简短摘要 |
| type | 字符串 | 是 | 对象的类型，始终为 `summary_text` |
##### 项目引用 [#项目引用]
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | ----------------------------- |
| id | 字符串 | 是 | 要引用的项目的ID |
| type | 字符串 | 否 | 要引用的项目类型，始终为 `item_reference` |
#### model [#model]
**类型**: 字符串\
**必需**: 是
用于生成响应的模型ID，例如 gpt-4.1 或 o3。OpenAI 提供各种具有不同能力、性能特性和价格点的模型。请参阅模型指南以浏览和比较可用模型。
#### include [#include]
**类型**: 数组或null\
**必需**: 否
指定要在模型响应中包含的附加输出数据。当前支持的值包括：
| 值 | 描述 |
| --------------------------------------- | ------------------ |
| `file_search_call.results` | 包含文件搜索工具调用的搜索结果 |
| `message.input_image.image_url` | 包含输入消息中的图像URL |
| `computer_call_output.output.image_url` | 包含电脑调用输出中的图像URL |
| `reasoning.encrypted_content` | 在推理项输出中包含推理标记的加密版本 |
#### instructions [#instructions]
**类型**: 字符串或null\
**必需**: 否
作为模型上下文中的第一项插入系统（或开发者）消息。
当与 `previous_response_id` 一起使用时，前一个响应中的指令不会被带到下一个响应。这使得在新响应中轻松切换系统（开发者）消息变得简单。
#### max\_output\_tokens [#max_output_tokens]
**类型**: 整数或null\
**必需**: 否
可以为响应生成的令牌数量的上限，包括可见输出令牌和推理令牌。
#### metadata [#metadata]
**类型**: 对象\
**必需**: 否
可以附加到对象的16个键值对集合。这对于以结构化格式存储对象的其他信息很有用,并可以通过 API 或仪表板查询对象。
键是最大长度为64个字符的字符串。值是最大长度为512个字符的字符串。
#### parallel\_tool\_calls [#parallel_tool_calls]
**类型**: 布尔值或null\
**必需**: 否\
**默认值**: true
是否允许模型并行运行工具调用。
#### previous\_response\_id [#previous_response_id]
**类型**: 字符串或null\
**必需**: 否
模型的前一个响应的唯一ID。使用此参数创建多轮对话。了解更多关于对话状态。
#### reasoning [#reasoning]
**类型**: 对象或null\
**必需**: 否\
**仅适用于o系列模型**
推理模型的配置选项。
| 属性 | 类型 | 必需 | 描述 |
| ----------------- | -------- | -- | ------------------------------------------------------------------------------- |
| effort | 字符串或null | 否 | 推理的努力程度，可选值: `low`, `medium`, `high`。默认值为 `medium`。降低推理努力可以加快响应速度并减少响应中用于推理的令牌数 |
| summary | 字符串或null | 否 | 模型执行的推理摘要。这对于调试和理解模型的推理过程很有用。可选值: `auto`, `concise`, `detailed` |
| generate\_summary | 字符串或null | 否 | **已弃用**: 请使用 `summary` 替代。模型执行的推理摘要。可选值: `auto`, `concise`, `detailed` |
#### service\_tier [#service_tier]
**类型**: 字符串或null\
**必需**: 否\
**默认值**: auto
指定用于处理请求的延迟层级。此参数与订阅了 scale tier 服务的客户相关：
| 值 | 描述 |
| --------- | -------------------------------------------------------------------------------------------------- |
| `auto` | 如果项目启用了 Scale tier，系统将使用 scale tier 信用直到用完；如果项目未启用 Scale tier，请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 |
| `default` | 请求将使用默认服务层级处理，具有较低的正常运行时间 SLA 且无延迟保证 |
| `flex` | 请求将使用 Flex Processing 服务层级处理。了解更多信息请参阅官方文档 |
当未设置此参数时，默认行为为 `auto`。
当设置此参数时，响应体将包含已使用的 `service_tier`。
#### store [#store]
**类型**: 布尔值或null\
**必需**: 否\
**默认值**: true
是否存储生成的模型响应以供以后通过 API 检索。
#### stream [#stream]
**类型**: 布尔值或null\
**必需**: 否\
**默认值**: false
如果设置为 true，模型响应数据将在生成时使用服务器发送的事件流式传输到客户端。
#### temperature [#temperature]
**类型**: 数字或null\
**必需**: 否\
**默认值**: 1
要使用的采样温度，介于 0 和 2 之间。较高的值（如0.8）会使输出更加随机，而较低的值（如0.2）会使其更加集中和确定性。我们通常建议更改此值或 `top_p`，但不要同时更改。
#### text [#text]
**类型**: 对象\
**必需**: 否
模型文本响应的配置选项。可以是纯文本或结构化JSON数据。
| 属性 | 类型 | 必需 | 描述 |
| ------ | -- | -- | ----------- |
| format | 对象 | 否 | 指定模型必须输出的格式 |
配置 `{ "type": "json_schema" }` 启用结构化输出，确保模型将匹配您提供的JSON模式。更多信息请参阅结构化输出指南。
默认格式为 `{ "type": "text" }`，没有其他选项。
**不推荐用于gpt-4o及更新的模型**：
设置为 `{ "type": "json_object" }` 启用较旧的JSON模式，确保模型生成的消息是有效的JSON。对于支持的模型，首选使用 `json_schema`。
##### 文本格式类型 [#文本格式类型]
###### 文本 (Text) [#文本-text]
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | -------------------- |
| type | 字符串 | 是 | 定义的响应格式类型。始终为 `text` |
###### JSON模式 (JSON Schema) [#json模式-json-schema]
| 属性 | 类型 | 必需 | 描述 |
| ----------- | -------- | -- | ------------------------------------------------------------------------------------------ |
| name | 字符串 | 是 | 响应格式的名称。必须包含a-z, A-Z, 0-9，或包含下划线和破折号，最大长度为64 |
| schema | 对象 | 是 | 响应格式的模式，描述为JSON Schema对象 |
| type | 字符串 | 是 | 定义的响应格式类型。始终为 `json_schema` |
| description | 字符串 | 否 | 响应格式用途的描述，模型用它来确定如何以该格式响应 |
| strict | 布尔值或null | 否 | 是否在生成输出时启用严格模式遵循。默认为 `false`。如果设置为 `true`，模型将始终遵循 schema 字段中定义的确切模式。严格模式下只支持JSON Schema的子集 |
###### JSON对象 (JSON Object) [#json对象-json-object]
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | --------------------------- |
| type | 字符串 | 是 | 定义的响应格式类型。始终为 `json_object` |
注意：如果没有指示模型这样做的系统或用户消息，模型将不会生成JSON。对于支持的模型，建议使用 `json_schema`。
#### tool\_choice [#tool_choice]
**类型**: 字符串或对象\
**必需**: 否
模型如何选择生成响应时使用的工具（或多个工具）。请参阅 `tools` 参数了解如何指定模型可以调用的工具。
##### 可能的类型 [#可能的类型-1]
###### 工具选择模式 (Tool choice mode) [#工具选择模式-tool-choice-mode]
**类型**: 字符串
控制模型是否调用工具以及调用哪种工具。
| 值 | 描述 |
| ---------- | ----------------------- |
| `none` | 模型不会调用任何工具，而是生成一条消息 |
| `auto` | 模型可以在生成消息或调用一个或多个工具之间选择 |
| `required` | 模型必须调用一个或多个工具 |
###### 托管工具 (Hosted tool) [#托管工具-hosted-tool]
**类型**: 对象
指示模型应使用内置工具生成响应。
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | ---------------------------------------------------------------------------- |
| type | 字符串 | 是 | 模型应使用的托管工具类型。允许的值有：`file_search`、`web_search_preview`、`computer_use_preview` |
###### 函数工具 (Function tool) [#函数工具-function-tool]
**类型**: 对象
使用此选项强制模型调用特定函数。
| 属性 | 类型 | 必需 | 描述 |
| ---- | --- | -- | ----------------------- |
| name | 字符串 | 是 | 要调用的函数名称 |
| type | 字符串 | 是 | 对于函数调用，类型始终为 `function` |
#### tools [#tools]
**类型**: 数组\
**必需**: 否
模型在生成响应时可能调用的工具数组。你可以通过设置 `tool_choice` 参数来指定使用哪个工具。
你可以提供给模型的两类工具是：
* **内置工具**：由OpenAI提供的扩展模型能力的工具，如网络搜索或文件搜索。
* **函数调用（自定义工具）**：由您定义的函数，使模型能够调用您自己的代码。
##### 文件搜索工具 (File search) [#文件搜索工具-file-search]
**类型**: 对象
一个搜索已上传文件中相关内容的工具。
| 属性 | 类型 | 必需 | 描述 |
| ------------------ | --- | -- | --------------------------- |
| type | 字符串 | 是 | 文件搜索工具的类型，始终为 `file_search` |
| vector\_store\_ids | 数组 | 是 | 要搜索的向量存储ID列表 |
| filters | 对象 | 否 | 要应用的过滤器 |
| max\_num\_results | 整数 | 否 | 返回的最大结果数。此数字应介于1到50之间（含） |
| ranking\_options | 对象 | 否 | 搜索排名选项 |
###### 过滤器类型 [#过滤器类型]
**比较过滤器 (Comparison Filter)**
| 属性 | 类型 | 必需 | 描述 |
| ----- | ---------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| key | 字符串 | 是 | 要与值进行比较的键 |
| type | 字符串 | 是 | 指定比较运算符: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`
- eq: 等于
- ne: 不等于
- gt: 大于
- gte: 大于等于
- lt: 小于
- lte: 小于等于 |
| value | 字符串/数字/布尔值 | 是 | 要与属性键比较的值；支持字符串、数字或布尔类型 |
**复合过滤器 (Compound Filter)**
| 属性 | 类型 | 必需 | 描述 |
| ------- | --- | -- | -------------------------- |
| filters | 数组 | 是 | 要组合的过滤器数组。项目可以是比较过滤器或复合过滤器 |
| type | 字符串 | 是 | 操作类型: `and` 或 `or` |
###### 排名选项 [#排名选项]
| 属性 | 类型 | 必需 | 描述 |
| ---------------- | --- | -- | -------------------------------------------------- |
| ranker | 字符串 | 否 | 文件搜索使用的排名器 |
| score\_threshold | 数字 | 否 | 文件搜索的分数阈值，介于0和1之间的数字。接近1的数字将尝试仅返回最相关的结果，但可能返回更少的结果 |
##### 函数工具 (Function) [#函数工具-function]
**类型**: 对象
定义模型可以选择调用的您自己代码中的函数。
| 属性 | 类型 | 必需 | 描述 |
| ----------- | --- | -- | ---------------------- |
| type | 字符串 | 是 | 函数工具的类型，始终为 `function` |
| name | 字符串 | 是 | 要调用的函数名称 |
| parameters | 对象 | 是 | 描述函数参数的JSON模式对象 |
| strict | 布尔值 | 是 | 是否强制严格参数验证。默认为 `true` |
| description | 字符串 | 否 | 函数的描述。模型用它来确定是否调用函数 |
##### 网络搜索工具 (Web search preview) [#网络搜索工具-web-search-preview]
**类型**: 对象
此工具搜索网络上的相关结果，用于响应。
| 属性 | 类型 | 必需 | 描述 |
| --------------------- | --- | -- | --------------------------------------------------------------------- |
| type | 字符串 | 是 | 网络搜索工具的类型。可选值: `web_search_preview` 或 `web_search_preview_2025_03_11` |
| search\_context\_size | 字符串 | 否 | 对用于搜索的上下文窗口空间量的高级指导。可选值: `low`, `medium`, `high`。默认为 `medium` |
| user\_location | 对象 | 否 | 用户的位置 |
| domains | 数组 | 否 | 限制搜索的域名列表 |
###### 用户位置 [#用户位置]
| 属性 | 类型 | 必需 | 描述 |
| -------- | --- | -- | ----------------------------------- |
| type | 字符串 | 是 | 位置近似类型。始终为 `approximate` |
| city | 字符串 | 否 | 用户所在城市的自由文本输入，例如 "San Francisco" |
| country | 字符串 | 否 | 用户的两字母ISO国家代码，例如 "US" |
| region | 字符串 | 否 | 用户所在区域的自由文本输入，例如 "California" |
| timezone | 字符串 | 否 | 用户的IANA时区，例如 "America/Los\_Angeles" |
##### 计算机使用工具 (Computer use preview) [#计算机使用工具-computer-use-preview]
**类型**: 对象
控制虚拟计算机的工具。
| 属性 | 类型 | 必需 | 描述 |
| --------------- | --- | -- | ------------------------------------- |
| type | 字符串 | 是 | 计算机使用工具的类型。始终为 `computer_use_preview` |
| display\_height | 整数 | 是 | 计算机显示器的高度 |
| display\_width | 整数 | 是 | 计算机显示器的宽度 |
| environment | 字符串 | 是 | 要控制的计算机环境类型 |
#### top\_p [#top_p]
**类型**: 数字或null\
**必需**: 否\
**默认值**: 1
一种替代采样温度的方法，称为核采样，其中模型考虑具有 top\_p 概率质量的标记结果。因此，0.1 意味着只考虑包含前 10% 概率质量的标记。
我们通常建议更改此值或 `temperature`，但不要同时更改。
#### truncation [#truncation]
**类型**: 字符串或null\
**必需**: 否\
**默认值**: disabled
用于模型响应的截断策略：
| 值 | 描述 |
| ---------- | -------------------------------------------------------- |
| `auto` | 如果此响应和前一个响应的上下文超过模型的上下文窗口大小，模型将通过删除对话中间的输入项来截断响应以适应上下文窗口 |
| `disabled` | 如果模型响应将超过模型的上下文窗口大小，请求将失败并显示400错误 |
#### user [#user]
**类型**: 字符串\
**必需**: 否
表示最终用户的唯一标识符，可以帮助OpenAI监控和检测滥用行为。
## 📥 响应 [#-响应]
返回一个响应对象。
### 成功响应 [#成功响应]
返回一个响应对象，如果请求被流式传输，则返回响应对象的流式序列。
#### id [#id]
* 类型：字符串
* 说明：响应的唯一标识符
#### object [#object]
* 类型：字符串
* 说明：对象类型,值为 "response"
#### created\_at [#created_at]
* 类型：整数
* 说明：响应创建时间戳
#### status [#status]
* 类型：字符串
* 说明：响应状态，如 "completed"、"in\_progress" 等
#### error [#error]
* 类型：对象或null
* 说明：如果发生错误，包含错误信息
#### incomplete\_details [#incomplete_details]
* 类型：对象或null
* 说明：如果响应不完整，包含详细信息
#### instructions [#instructions-1]
* 类型：字符串或null
* 说明：提供给模型的系统指令
#### max\_output\_tokens [#max_output_tokens-1]
* 类型：整数或null
* 说明：最大输出标记数
#### model [#model-1]
* 类型：字符串
* 说明：使用的模型名称
#### output [#output]
* 类型：数组
* 说明：包含生成的回复和工具调用
* 可能包含:
* 消息对象（`type`: "message"）
* 工具使用对象（`type`: "tool\_use"）
#### parallel\_tool\_calls [#parallel_tool_calls-1]
* 类型：布尔值
* 说明：是否启用并行工具调用
#### previous\_response\_id [#previous_response_id-1]
* 类型：字符串或null
* 说明：前一个响应的ID（用于多轮对话）
#### reasoning [#reasoning-1]
* 类型：对象
* 说明：推理相关信息
#### store [#store-1]
* 类型：布尔值
* 说明：是否存储此响应
#### temperature [#temperature-1]
* 类型：数字
* 说明：使用的采样温度
#### text [#text-1]
* 类型：对象
* 说明：文本输出格式配置
#### tool\_choice [#tool_choice-1]
* 类型：字符串
* 说明：工具选择策略
#### tools [#tools-1]
* 类型：数组
* 说明：可用工具列表
#### top\_p [#top_p-1]
* 类型：数字
* 说明：核采样阈值
#### truncation [#truncation-1]
* 类型：字符串
* 说明：截断策略
#### usage [#usage]
* 类型：对象
* 说明：token 使用统计
* 属性:
* `input_tokens`: 输入使用的 token 数
* `input_tokens_details`: 输入token详细信息
* `output_tokens`: 输出使用的 token 数
* `output_tokens_details`: 输出token详细信息
* `total_tokens`: 总 token 数
#### user [#user-1]
* 类型：字符串或null
* 说明：用户标识符
#### metadata [#metadata-1]
* 类型：对象
* 说明：附加的元数据信息
# OpenAI 视频格式（Sora格式） (/zh/api/openai-video)
调用OpenAI视频生成接口生成视频，支持 Sora 等模型，也支持使用 OpenAI 视频格式调用可灵，即梦和 vidu。
## 生成视频 [#生成视频]
### API 端点 [#api-端点]
```
POST /v1/videos
```
### 请求头 [#请求头]
| 参数 | 类型 | 必填 | 描述 |
| ------------- | ------ | -- | ------------------------ |
| Authorization | string | 是 | 用户认证令牌 (Bearer: sk-xxxx) |
### 请求参数 (multipart/form-data) [#请求参数-multipartform-data]
| 参数 | 类型 | 必填 | 描述 |
| ---------------- | ------ | -- | -------------------------------------- |
| prompt | string | 是 | 描述要生成视频的文本提示词 |
| model | string | 否 | 视频生成模型，默认为 sora-2 |
| seconds | string | 否 | 视频时长（秒），默认为 4 秒 |
| size | string | 否 | 输出分辨率，格式为宽度x高度，默认为 720x1280 |
| input\_reference | file | 否 | 输入图片文件（图生视频时使用），输入图像必须符合对应的宽度和高度(size) |
| metadata | string | 否 | 扩展参数（JSON字符串格式） |
#### metadata 参数说明 [#metadata-参数说明]
metadata 参数的作用是传递非sora模型特有的参数，比如阿里云万相的图片URL、水印、prompt智能改写等。metadata 参数的格式为 JSON 字符串，比如：
```json
{
"img_url": "https://example.com/image.jpg",
"watermark": false,
"prompt_extend": true
}
```
### 请求示例 [#请求示例]
#### 文生视频 (仅文本提示) [#文生视频-仅文本提示]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级" \
-F "model=sora-2" \
-F "seconds=5" \
-F "size=1920x1080"
```
#### 图生视频 (文本提示 + 图片文件) [#图生视频-文本提示--图片文件]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=猫咪慢慢睁开眼睛，伸懒腰" \
-F "model=sora-2" \
-F "seconds=3" \
-F "size=1920x1080" \
-F "input_reference=@/path/to/cat.jpg"
```
#### 阿里云万相视频生成示例 [#阿里云万相视频生成示例]
##### 文生视频 (万相2.5) [#文生视频-万相25]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=一只可爱的小猫在花园里玩耍，阳光明媚，色彩鲜艳" \
-F "model=wan2.5-t2v-preview" \
-F "seconds=5" \
-F "size=1920*1080"
```
##### 图生视频 (万相2.5) [#图生视频-万相25]
```bash
curl https://api.zipflow.xyz/v1/videos \
-H "Authorization: Bearer sk-xxxx" \
-F "prompt=让这张图片动起来，添加自然的运动效果" \
-F "model=wan2.5-i2v-preview" \
-F "seconds=5" \
-F "size=1280P" \
-F 'metadata={"img_url":"https://example.com/image.jpg"}'
```
### 响应格式 [#响应格式]
#### 201 - 创建成功 [#201---创建成功]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "processing",
"progress": 0
}
```
#### 响应字段说明 [#响应字段说明]
| 字段 | 类型 | 描述 |
| ----------- | ------- | --------------------- |
| id | string | 视频任务ID |
| object | string | 对象类型，固定为 "video" |
| model | string | 使用的模型名称 |
| created\_at | integer | 创建时间戳 |
| status | string | 任务状态（processing: 处理中） |
| progress | integer | 生成进度百分比 |
## 查询视频 [#查询视频]
根据任务ID查询视频生成任务的状态和结果
### API 端点 [#api-端点-1]
```
GET /v1/videos/{video_id}
```
### 路径参数 [#路径参数]
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | -- | ------ |
| video\_id | string | 是 | 视频任务ID |
### 请求示例 [#请求示例-1]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### 响应格式 [#响应格式-1]
#### 200 - 成功响应 [#200---成功响应]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard"
}
```
#### 响应字段说明 [#响应字段说明-1]
| 字段 | 类型 | 描述 |
| ----------- | ------- | ------------------------------------------------ |
| id | string | 视频任务ID |
| object | string | 对象类型，固定为 "video" |
| model | string | 使用的模型名称 |
| created\_at | integer | 创建时间戳 |
| status | string | 任务状态（processing: 处理中, succeeded: 成功, failed: 失败） |
| progress | integer | 生成进度百分比 |
| expires\_at | integer | 资源过期时间戳 |
| size | string | 视频分辨率 |
| seconds | string | 视频时长（秒） |
| quality | string | 视频质量 |
| url | string | 视频下载链接（完成时） |
## 获取视频任务状态 [#获取视频任务状态]
根据任务ID获取视频生成任务的详细信息
### API 端点 [#api-端点-2]
```
GET /v1/videos/{video_id}
```
### 路径参数 [#路径参数-1]
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | -- | ----------- |
| video\_id | string | 是 | 要获取的视频任务标识符 |
### 请求示例 [#请求示例-2]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### 响应格式 [#响应格式-2]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard",
"remixed_from_video_id": null,
"error": null
}
```
#### 响应字段说明 [#响应字段说明-2]
| 字段 | 类型 | 描述 |
| ------------------------ | ------- | ------------------------- |
| id | string | 视频任务的唯一标识符 |
| object | string | 对象类型，固定为 "video" |
| model | string | 生成视频的模型名称 |
| status | string | 视频任务的当前生命周期状态 |
| progress | integer | 生成任务的近似完成百分比 |
| created\_at | integer | 任务创建时的Unix时间戳（秒） |
| expires\_at | integer | 可下载资源过期时的Unix时间戳（秒），如果已设置 |
| size | string | 生成视频的分辨率 |
| seconds | string | 生成视频片段的时长（秒） |
| quality | string | 视频质量 |
| remixed\_from\_video\_id | string | 如果此视频是混音，则为源视频的标识符 |
| error | object | 如果生成失败，则包含错误信息的对象 |
## 获取视频内容 [#获取视频内容]
下载已完成的视频内容
### API 端点 [#api-端点-3]
```
GET /v1/videos/{video_id}/content
```
### 路径参数 [#路径参数-2]
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | -- | --------- |
| video\_id | string | 是 | 要下载的视频标识符 |
### 查询参数 [#查询参数]
| 参数 | 类型 | 必填 | 描述 |
| ------- | ------ | -- | -------------------- |
| variant | string | 否 | 要返回的可下载资源类型，默认为MP4视频 |
### 请求示例 [#请求示例-3]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123/content' \
-H "Authorization: Bearer sk-xxxx" \
-o "video.mp4"
```
### 响应说明 [#响应说明]
直接返回视频文件流，Content-Type为 `video/mp4`
#### 响应头 [#响应头]
| 字段 | 描述 |
| ------------------- | -------------------- |
| Content-Type | 视频文件类型，通常为 video/mp4 |
| Content-Length | 视频文件大小（字节） |
| Content-Disposition | 文件下载信息 |
## 错误响应 [#错误响应]
### 400 - 请求参数错误 [#400---请求参数错误]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 401 - 未授权 [#401---未授权]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 403 - 无权限 [#403---无权限]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 404 - 任务不存在 [#404---任务不存在]
```json
{
"error": {
"message": "string",
"type": "invalid_request_error"
}
}
```
### 500 - 服务器内部错误 [#500---服务器内部错误]
```json
{
"error": {
"message": "string",
"type": "server_error"
}
}
```
## 支持的模型 [#支持的模型]
### OpenAI兼容 [#openai兼容]
* `sora-2`: Sora视频生成模型
### 通过OpenAI格式调用的其他服务 [#通过openai格式调用的其他服务]
* 阿里云万相 (Ali Wan): 使用 `wan2.5-t2v-preview` (文生视频), `wan2.5-i2v-preview` (图生视频), `wan2.2-i2v-flash`, `wan2.2-i2v-plus`, `wanx2.1-i2v-plus`, `wanx2.1-i2v-turbo`
* 可灵AI (Kling): 使用 `kling-v1`, `kling-v2-master`
* 即梦 (Jimeng): 使用 `jimeng_vgfm_t2v_l20`, `jimeng_vgfm_i2v_l20`
* Vidu: 使用 `viduq1`
## 阿里云万相特殊说明 [#阿里云万相特殊说明]
### 支持的功能 [#支持的功能]
* **文生视频 (t2v)**: 仅使用文本提示词生成视频
* **图生视频 (i2v)**: 使用文本提示词+图片生成视频
* **首尾帧生视频 (kf2v)**: 指定首帧和尾帧图片生成视频
* **音频生成 (s2v)**: 支持音频与视频结合
### 分辨率支持 [#分辨率支持]
* **480P**: 832×480, 480×832, 624×624
* **720P**: 1280×720, 720×1280, 960×960, 1088×832, 832×1088
* **1080P**: 1920×1080, 1080×1920, 1440×1440, 1632×1248, 1248×1632
### 特殊参数 [#特殊参数]
* `watermark`: 是否添加水印（默认false）
* `prompt_extend`: 是否开启prompt智能改写（默认true）
* `audio`: 是否添加音频（仅wan2.5支持）
* `seed`: 随机数种子
### 模型特点 [#模型特点]
* **wan2.5-i2v-preview**: 万相2.5 preview版本，支持有声视频，推荐使用
* **wan2.2-i2v-flash**: 万相2.2极速版，生成速度快，无声视频
* **wan2.2-i2v-plus**: 万相2.2专业版，画质更高，无声视频
* **wanx2.1-i2v-plus**: 万相2.1专业版，稳定版本
* **wanx2.1-i2v-turbo**: 万相2.1极速版
## 最佳实践 [#最佳实践]
1. **请求格式**: 使用 `multipart/form-data` 格式，这是OpenAI官方推荐的方式
2. **input\_reference参数**: 用于图生视频功能，上传图片文件时使用 `@filename` 语法
3. **提示词优化**: 使用详细、具体的描述词，包含风格、质量要求
4. **参数设置**: 根据需求合理设置时长和分辨率
5. **阿里云万相特殊说明**:
* **不支持直接上传文件**，所有资源通过URL传递
* 使用 `metadata` 参数传递所有扩展参数（JSON字符串格式）
* 图生视频使用 `metadata.img_url` 传递图片URL
* 首尾帧生视频使用 `metadata.first_frame_url` 和 `metadata.last_frame_url`
6. **错误处理**: 实现适当的重试机制和错误处理
7. **异步处理**: 视频生成是异步任务，需要轮询查询状态
8. **资源管理**: 及时下载并清理不需要的视频文件
## JavaScript 示例 [#javascript-示例]
### 使用 FormData (推荐) [#使用-formdata-推荐]
```javascript
async function generateVideoWithFormData() {
const formData = new FormData();
formData.append('prompt', '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级');
formData.append('model', 'sora-2');
formData.append('seconds', '5');
formData.append('size', '1920x1080');
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// 图生视频示例
async function generateVideoWithImage() {
const formData = new FormData();
formData.append('prompt', '猫咪慢慢睁开眼睛，伸懒腰');
formData.append('model', 'sora-2');
formData.append('seconds', '3');
formData.append('size', '1920x1080');
// 添加图片文件
const imageFile = document.getElementById('imageInput').files[0];
formData.append('input_reference', imageFile);
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
```
### 阿里云万相调用示例 [#阿里云万相调用示例]
```javascript
// 阿里云万相文生视频
async function generateAliVideo() {
const formData = new FormData();
formData.append('prompt', '一只可爱的小猫在花园里玩耍，阳光明媚，色彩鲜艳');
formData.append('model', 'wan2.5-t2v-preview');
formData.append('seconds', '5');
formData.append('size', '1920*1080');
formData.append('metadata', JSON.stringify({
watermark: false,
prompt_extend: true
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// 阿里云万相图生视频
async function generateAliImageToVideo() {
const formData = new FormData();
formData.append('prompt', '让这张图片动起来，添加自然的运动效果');
formData.append('model', 'wan2.5-i2v-preview');
formData.append('seconds', '3');
formData.append('resolution', '720P');
formData.append('input_reference', imageFile);
formData.append('metadata', JSON.stringify({
watermark: false,
prompt_extend: true
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
// 阿里云万相首尾帧生视频
async function generateAliKeyframeVideo() {
const formData = new FormData();
formData.append('prompt', '从开始到结束的平滑过渡动画');
formData.append('model', 'wan2.2-kf2v-flash');
formData.append('seconds', '4');
formData.append('metadata', JSON.stringify({
first_frame_url: 'https://example.com/start.jpg',
last_frame_url: 'https://example.com/end.jpg',
resolution: '720P',
watermark: false
}));
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx'
},
body: formData
});
const result = await response.json();
return result.id;
}
```
# 查询视频 API (/zh/api/query-video)
根据任务ID查询视频生成任务的状态和结果。
## 查询视频状态 [#查询视频状态]
### API 端点 [#api-端点]
```
GET /v1/video/generations/{task_id}
```
### 路径参数 [#路径参数]
| 参数 | 类型 | 必填 | 描述 |
| -------- | ------ | -- | ---- |
| task\_id | string | 是 | 任务ID |
### 请求示例 [#请求示例]
```bash
curl 'https://api.zipflow.xyz/v1/video/generations/{task_id}' \
-H "Authorization: Bearer sk-xxxx"
```
### 响应格式 [#响应格式]
#### 200 - 成功响应 [#200---成功响应]
```json
{
"error": null,
"format": "mp4",
"metadata": {
"duration": 5,
"fps": 30,
"height": 512,
"seed": 20231234,
"width": 512
},
"status": "succeeded",
"task_id": "abcd1234efgh",
"url": "https://example.com/video.mp4"
}
```
#### 响应字段说明 [#响应字段说明]
| 字段 | 类型 | 描述 |
| -------- | ------ | ------------------------------------------------ |
| task\_id | string | 任务ID |
| status | string | 任务状态（processing: 处理中, succeeded: 成功, failed: 失败） |
| format | string | 视频格式 |
| url | string | 视频资源URL（成功时） |
| metadata | object | 结果元数据 |
| error | object | 错误信息（成功时为null） |
### 状态说明 [#状态说明]
| 状态 | 描述 |
| ------------ | --------- |
| processing | 任务正在处理中 |
| queued | 任务已排队等待处理 |
| in\_progress | 任务正在进行中 |
| succeeded | 任务成功完成 |
| failed | 任务失败 |
## OpenAI兼容格式查询 [#openai兼容格式查询]
### API 端点 [#api-端点-1]
```
GET /v1/videos/{video_id}
```
### 路径参数 [#路径参数-1]
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | -- | ------ |
| video\_id | string | 是 | 视频任务ID |
### 请求示例 [#请求示例-1]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123' \
-H "Authorization: Bearer sk-xxxx"
```
### 响应格式 [#响应格式-1]
```json
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"created_at": 1640995200,
"status": "succeeded",
"progress": 100,
"expires_at": 1641081600,
"size": "1920x1080",
"seconds": "5",
"quality": "standard",
"url": "https://example.com/video.mp4"
}
```
#### 响应字段说明 [#响应字段说明-1]
| 字段 | 类型 | 描述 |
| ----------- | ------- | ------------------------- |
| id | string | 视频任务的唯一标识符 |
| object | string | 对象类型，固定为 "video" |
| model | string | 生成视频的模型名称 |
| status | string | 视频任务的当前生命周期状态 |
| progress | integer | 生成任务的近似完成百分比 |
| created\_at | integer | 任务创建时的Unix时间戳（秒） |
| expires\_at | integer | 可下载资源过期时的Unix时间戳（秒），如果已设置 |
| size | string | 生成视频的分辨率 |
| seconds | string | 生成视频片段的时长（秒） |
| quality | string | 视频质量 |
| url | string | 视频下载链接（完成时） |
## 获取视频内容 [#获取视频内容]
### API 端点 [#api-端点-2]
```
GET /v1/videos/{video_id}/content
```
### 路径参数 [#路径参数-2]
| 参数 | 类型 | 必填 | 描述 |
| --------- | ------ | -- | --------- |
| video\_id | string | 是 | 要下载的视频标识符 |
### 查询参数 [#查询参数]
| 参数 | 类型 | 必填 | 描述 |
| ------- | ------ | -- | -------------------- |
| variant | string | 否 | 要返回的可下载资源类型，默认为MP4视频 |
### 请求示例 [#请求示例-2]
```bash
curl 'https://api.zipflow.xyz/v1/videos/video_123/content' \
-H "Authorization: Bearer sk-xxxx" \
-o "video.mp4"
```
### 响应说明 [#响应说明]
直接返回视频文件流，Content-Type为 `video/mp4`
#### 响应头 [#响应头]
| 字段 | 描述 |
| ------------------- | -------------------- |
| Content-Type | 视频文件类型，通常为 video/mp4 |
| Content-Length | 视频文件大小（字节） |
| Content-Disposition | 文件下载信息 |
## 错误响应 [#错误响应]
### 400 - 请求参数错误 [#400---请求参数错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 401 - 未授权 [#401---未授权]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 403 - 无权限 [#403---无权限]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
### 404 - 任务不存在 [#404---任务不存在]
```json
{
"code": null,
"message": "Task not found",
"param": "task_id",
"type": "invalid_request_error"
}
```
### 500 - 服务器内部错误 [#500---服务器内部错误]
```json
{
"code": null,
"message": "string",
"param": "string",
"type": "string"
}
```
## 轮询策略 [#轮询策略]
### 推荐轮询间隔 [#推荐轮询间隔]
1. **初始轮询**: 提交任务后等待 2-3 秒再开始轮询
2. **轮询频率**:
* 前30秒: 每5秒轮询一次
* 30秒-2分钟: 每10秒轮询一次
* 2分钟后: 每30秒轮询一次
3. **超时处理**: 建议设置5-10分钟的总超时时间
### 轮询示例代码 [#轮询示例代码]
```javascript
async function pollVideoStatus(taskId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/video/generations/${taskId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`Video generation failed: ${result.error?.message || 'Unknown error'}`);
}
// 等待后重试
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`Attempt ${attempt + 1} failed:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('Max polling attempts reached');
}
```
## 最佳实践 [#最佳实践]
1. **状态检查**: 定期检查任务状态，避免过度频繁的请求
2. **错误处理**: 妥善处理各种错误情况，包括网络错误和API错误
3. **超时设置**: 设置合理的超时时间，避免无限等待
4. **缓存策略**: 对于已完成的视频，可以考虑缓存结果
5. **并发控制**: 避免同时发起过多查询请求
6. **资源清理**: 及时下载并清理不需要的视频文件
# Suno 音乐格式（Music） (/zh/api/suno-music)
该接口 **非Suno官方的接口**，而是基于作者 **柏拉图** 的开源项目 [**Suno-API**](https://github.com/Suno-API/Suno-API) 实现的Suno代理接口。
这里非常感谢作者的贡献，让我们可以方便使用Suno的强大功能，如果有时间，请给作者一个Star。
## 📝 简介 [#-简介]
Suno Music API 提供了一系列音乐生成和处理的功能，包括:
* 根据提示生成歌曲（灵感模式、自定义模式）
* 续写已有歌曲
* 拼接多个音频片段
* 生成歌词
* 上传音频
通过 API 可以方便地将 AI 音乐生成能力集成到你的应用中。
## 💡 请求示例 [#-请求示例]
### 生成歌曲 ✅ [#生成歌曲-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/music' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"prompt":"[Verse]\nWalking down the streets\nBeneath the city lights\nNeon signs flickering\nLighting up the night\nHeart beating faster\nLike a drum in my chest\nI'\''m alive in this moment\nFeeling so blessed\n\nStilettos on the pavement\nStepping with grace\nSurrounded by the people\nMoving at their own pace\nThe rhythm of the city\nIt pulses in my veins\nLost in the energy\nAs my worries drain\n\n[Verse 2]\nConcrete jungle shining\nWith its dazzling glow\nEvery corner hiding secrets that only locals know\nA symphony of chaos\nBut it'\''s music to my ears\nThe hustle and the bustle\nWiping away my fears",
"tags":"emotional punk",
"mv":"chirp-v4",
"title":"City Lights"
}'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### 生成歌词 ✅ [#生成歌词-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/lyrics' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"prompt":"dance"
}'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### 上传音频 ❌ [#上传音频-]
```bash
curl --location 'https://api.zipflow.xyz/suno/uploads/audio-url' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"url":"http://cdnimg.example.com/ai/2024-06-18/d416d9c3c34eb22c7d8c094831d8dbd0.mp3"
}'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### 歌曲拼接 ❌ [#歌曲拼接-]
```bash
curl --location 'https://api.zipflow.xyz/suno/submit/concat' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"clip_id":"extend 后的 歌曲ID",
"is_infill": false
}'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":"736a6f88-bd29-4b1e-b110-37132a5325ac"
}
```
### 查询任务状态 ✅ [#查询任务状态-]
#### 批量查询 [#批量查询]
```bash
curl --location 'https://api.zipflow.xyz/suno/fetch' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"ids":["task_id"],
"action":"MUSIC"
}'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":[
{
"task_id":"346c5d10-a4a1-4f49-a851-66a7dae6cfaf",
"notify_hook":"",
"action":"MUSIC",
"status":"IN_PROGRESS",
"fail_reason":"",
"submit_time":1716191749,
"start_time":1716191786,
"finish_time":0,
"progress":"0%",
"data":[
{
"id":"e9893d04-6a63-4007-8473-64b706eca4d1",
"title":"Electric Dance Party",
"status":"streaming",
"metadata":{
"tags":"club banger high-energy edm",
"prompt":"略",
"duration":null,
"error_type":null,
"error_message":null,
"audio_prompt_id":null,
"gpt_description_prompt":"miku dance"
},
"audio_url":"https://audiopipe.suno.ai/?item_id=e9893d04-6a63-4007-8473-64b706eca4d1",
"image_url":"https://cdn1.suno.ai/image_e9893d04-6a63-4007-8473-64b706eca4d1.png",
"video_url":"",
"model_name":"chirp-v3",
"image_large_url":"https://cdn1.suno.ai/image_large_e9893d04-6a63-4007-8473-64b706eca4d1.png",
"major_model_version":"v3"
}
]
}
]
}
```
#### 单个查询 [#单个查询]
```bash
curl --location 'https://api.zipflow.xyz/suno/fetch/{{task_id}}' \
--header 'Authorization: Bearer $ZIPFLOW_API_KEY'
```
**响应示例:**
```json
{
"code":"success",
"message":"",
"data":{
"task_id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
"notify_hook":"",
"action":"LYRICS",
"status":"SUCCESS",
"fail_reason":"",
"submit_time":1716192124,
"start_time":1716192124,
"finish_time":1716192124,
"progress":"100%",
"data":{
"id":"f4a94d75-087b-4bb1-bd45-53ba293faf96",
"text":"略",
"title":"Electric Fantasy",
"status":"complete"
}
}
}
```
## 📮 请求 [#-请求]
所有请求都需在请求头中包含认证信息:
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
### 端点 [#端点]
#### 生成歌曲 [#生成歌曲]
```
POST /suno/submit/music
```
生成新的歌曲,支持灵感模式、自定义模式、续写。
#### 生成歌词 [#生成歌词]
```
POST /suno/submit/lyrics
```
根据提示生成歌词。
#### 上传音频 [#上传音频]
```
POST /suno/uploads/audio-url
```
上传音频文件。
#### 歌曲拼接 [#歌曲拼接]
```
POST /suno/submit/concat
```
将多个音频片段拼接为一首完整的歌曲。
#### 批量查询任务状态 [#批量查询任务状态]
```
POST /suno/fetch
```
批量获取多个任务的状态和结果。
#### 查询单个任务状态 [#查询单个任务状态]
```
GET /suno/fetch/{{task_id}}
```
查询单个任务的状态和结果。
### 请求体参数 [#请求体参数]
#### 生成歌曲 [#生成歌曲-1]
##### `prompt` [#prompt]
* 类型:String
* 必需:灵感模式无需,自定义模式必需
* 说明:歌词内容,在自定义模式下需提供
##### `mv` [#mv]
* 类型:String
* 必需:否
* 说明:模型版本,可选值:chirp-v3-0、chirp-v3-5,默认为 chirp-v3-0
##### `title` [#title]
* 类型:String
* 必需:灵感模式无需,自定义模式必需
* 说明:歌曲标题,在自定义模式下需提供
##### `tags` [#tags]
* 类型:String
* 必需:灵感模式无需,自定义模式必需
* 说明:歌曲风格标签,使用逗号分隔,在自定义模式下需提供
##### `make_instrumental` [#make_instrumental]
* 类型:Boolean
* 必需:否
* 说明:是否生成纯音乐,true 为生成纯音乐
##### `task_id` [#task_id]
* 类型:String
* 必需:续写时必需
* 说明:要续写的歌曲的任务 ID
##### `continue_at` [#continue_at]
* 类型:Float
* 必需:续写时必需
* 说明:从歌曲的第几秒开始续写
##### `continue_clip_id` [#continue_clip_id]
* 类型:String
* 必需:续写时必需
* 说明:要续写的歌曲的 clip ID
##### `gpt_description_prompt` [#gpt_description_prompt]
* 类型:String
* 必需:灵感模式必需,其他模式无需
* 说明:灵感来源的文字描述
##### `notify_hook` [#notify_hook]
* 类型:String
* 必需:否
* 说明:歌曲生成完成的回调通知地址
#### 生成歌词 [#生成歌词-1]
##### `prompt` [#prompt-1]
* 类型:String
* 必需:是
* 说明:歌词的主题或关键词
##### `notify_hook` [#notify_hook-1]
* 类型:String
* 必需:否
* 说明:歌词生成完成的回调通知地址
#### 上传音频 [#上传音频-1]
##### `url` [#url]
* 类型:String
* 必需:是
* 说明:要上传的音频文件的 URL 地址
#### 歌曲拼接 [#歌曲拼接-1]
##### `clip_id` [#clip_id]
* 类型:String
* 必需:是
* 说明:要拼接的歌曲片段的 ID
##### `is_infill` [#is_infill]
* 类型:Boolean
* 必需:否
* 说明:是否为填充模式
#### 任务查询 [#任务查询]
##### `ids` [#ids]
* 类型:String\[]
* 必需:是
* 说明:要查询的任务 ID 列表
##### `action` [#action]
* 类型:String
* 必需:否
* 说明:任务类型,可选值:MUSIC、LYRICS
## 📥 响应 [#-响应]
所有接口均返回统一的 JSON 格式响应:
```json
{
"code":"success",
"message":"",
"data":"{{RESULT}}"
}
```
### 成功响应 [#成功响应]
#### 基础响应字段 [#基础响应字段]
##### `code` [#code]
* 类型:String
* 说明:请求状态,success 为成功
##### `message` [#message]
* 类型:String
* 说明:请求失败时的错误信息
##### `data` [#data]
* 类型:根据不同接口而异
* 说明:请求成功时的返回数据
* 生成歌曲、歌词、上传音频、歌曲拼接接口:返回任务 ID 字符串
* 任务查询接口:返回任务对象或任务对象数组
#### 任务相关对象 [#任务相关对象]
##### 任务对象 [#任务对象]
###### `task_id` [#task_id-1]
* 类型:String
* 说明:任务 ID
###### `notify_hook` [#notify_hook-2]
* 类型:String
* 说明:任务完成后的回调通知地址
###### `action` [#action-1]
* 类型:String
* 说明:任务类型,可选值:MUSIC、LYRICS
###### `status` [#status]
* 类型:String
* 说明:任务状态,可选值:IN\_PROGRESS、SUCCESS、FAIL
###### `fail_reason` [#fail_reason]
* 类型:String
* 说明:任务失败原因
###### `submit_time` [#submit_time]
* 类型:Integer
* 说明:任务提交时间戳
###### `start_time` [#start_time]
* 类型:Integer
* 说明:任务开始时间戳
###### `finish_time` [#finish_time]
* 类型:Integer
* 说明:任务结束时间戳
###### `progress` [#progress]
* 类型:String
* 说明:任务进度百分比
###### `data` [#data-1]
* 类型:根据任务类型不同而异
* 说明:
* 音乐生成任务:歌曲对象数组
* 歌词生成任务:歌词对象
##### 歌曲对象 [#歌曲对象]
###### `id` [#id]
* 类型:String
* 说明:歌曲 ID
###### `title` [#title-1]
* 类型:String
* 说明:歌曲标题
###### `status` [#status-1]
* 类型:String
* 说明:歌曲状态
###### `metadata` [#metadata]
* 类型:Object
* 说明:歌曲元数据
* tags:歌曲风格标签
* prompt:生成歌曲使用的歌词
* duration:歌曲时长
* error\_type:错误类型
* error\_message:错误信息
* audio\_prompt\_id:音频 prompt ID
* gpt\_description\_prompt:灵感来源描述
###### `audio_url` [#audio_url]
* 类型:String
* 说明:歌曲音频的 URL 地址
###### `image_url` [#image_url]
* 类型:String
* 说明:歌曲封面图的 URL 地址
###### `video_url` [#video_url]
* 类型:String
* 说明:歌曲视频的 URL 地址
###### `model_name` [#model_name]
* 类型:String
* 说明:生成歌曲使用的模型名称
###### `major_model_version` [#major_model_version]
* 类型:String
* 说明:模型主版本号
##### 歌词对象 [#歌词对象]
###### `id` [#id-1]
* 类型:String
* 说明:歌词 ID
###### `text` [#text]
* 类型:String
* 说明:歌词内容
###### `title` [#title-2]
* 类型:String
* 说明:歌词标题
###### `status` [#status-2]
* 类型:String
* 说明:歌词状态
## 🌟 最佳实践 [#-最佳实践]
1. 提供尽量详细 、具体的歌曲或歌词生成提示,避免过于笼统或抽象
2. 查询任务状态时,轮询间隔建议为 2-5 秒,避免过于频繁
3. 灵感模式仅需提供 gpt\_description\_prompt 参数,API 会自动生成歌词、标题、标签等
4. 自定义模式需要提供 prompt、title、tags 参数,可以对歌曲有更多控制
5. 尽量使用最新版本的模型(如 chirp-v4),效果会更好
6. 使用回调通知功能(notify\_hook 参数)可以降低轮询频率,提高效率
7. 音乐续写、拼接功能可以在原有音乐基础上,生成更加丰富、完整的作品
8. 注意处理可能出现的异常和错误,如网络超时、参数校验失败等
# 令牌用量查询（Token Usage） (/zh/api/token-usage)
通过认证查询当前 Bearer Token 的额度使用情况：授予总量、已用、剩余、是否无限、模型限额及到期时间。
## 📮 端点 [#-端点]
```
GET /api/usage/token
```
* 需要在请求头中携带鉴权信息
* 仅返回当前请求所使用的 Token 的用量信息
## 🔐 鉴权 [#-鉴权]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
* 支持携带或不携带 `sk-` 前缀，服务端会自动兼容
* 缺少或无效的 Authorization 头将返回 401
## 💡 请求示例 [#-请求示例]
```bash
curl -X GET https://api.zipflow.xyz/api/usage/token \
-H "Authorization: Bearer $ZIPFLOW_API_KEY"
```
## ✅ 成功响应示例 [#-成功响应示例]
```json
{
"code": true,
"message": "ok",
"data": {
"object": "token_usage",
"name": "Default Token",
"total_granted": 1000000,
"total_used": 12345,
"total_available": 987655,
"unlimited_quota": false,
"model_limits": {
"gpt-4o-mini": true
},
"model_limits_enabled": false,
"expires_at": 0
}
}
```
## ❗ 错误响应示例 [#-错误响应示例]
* 缺少鉴权头：
```json
{
"success": false,
"message": "No Authorization header"
}
```
* 非 Bearer 方案：
```json
{
"success": false,
"message": "Invalid Bearer token"
}
```
* Token 查找失败（例如无效或已删除）：
```json
{
"success": false,
"message": "token not found"
}
```
## 🧾 字段说明（data） [#-字段说明data]
* `object`: 固定为 `token_usage`
* `name`: 令牌名称
* `total_granted`: 授予总量（= 已用 + 剩余）
* `total_used`: 已使用额度
* `total_available`: 可用剩余额度
* `unlimited_quota`: 是否为无限额度
* `model_limits`: 允许使用的模型列表
* `model_limits_enabled`: 是否启用模型限额
* `expires_at`: 到期时间的 Unix 时间戳（秒）。若永不过期返回 `0`（由后端将 `-1` 归一化为 `0`）
***
> 参考实现：`GET /api/usage/token` 新增于 PR [#1161](https://github.com/QuantumNous/zipflow/pull/1161)
# 模型列表（Model） (/zh/api/v1-models)
以标准 OpenAI `GET /v1/models` 格式列出您的 API 密钥可访问的模型。返回的 `id` 可作为推理请求中的 `model` 参数值。
## 📮 端点 [#-端点]
```
GET /v1/models
```
* 需要在请求头中携带鉴权信息
* 返回当前请求所使用的 Token 可访问的模型列表
## 🔐 鉴权 [#-鉴权]
在请求头中包含以下内容进行 API 密钥认证：
```
Authorization: Bearer $ZIPFLOW_API_KEY
```
* 支持携带或不携带 `sk-` 前缀，服务端会自动兼容
* 缺少或无效的 Authorization 头将返回 401
## 💡 请求示例 [#-请求示例]
```bash
curl https://api.zipflow.xyz/v1/models \
-H "Authorization: Bearer $ZIPFLOW_API_KEY"
```
## ✅ 成功响应示例 [#-成功响应示例]
```json
{
"object": "list",
"data": [
{
"id": "gpt-4.1",
"object": "model",
"created": 1686935002,
"owned_by": "openai"
},
{
"id": "claude-sonnet-4",
"object": "model",
"created": 1686935002,
"owned_by": "anthropic"
}
]
}
```
## ❗ 错误响应示例 [#-错误响应示例]
* 缺少鉴权头：
```json
{
"error": {
"message": "You did not provide an API key. Provide your API key in an Authorization header using Bearer auth.",
"type": "invalid_request_error",
"param": null,
"code": null
}
}
```
* API 密钥无效：
```json
{
"error": {
"message": "Incorrect API key provided.",
"type": "invalid_request_error",
"param": null,
"code": "invalid_api_key"
}
}
```
## 🧾 字段说明 [#-字段说明]
* `object`: 固定为 `list`
* `data`: 可用模型条目数组
* `id`: 模型标识符 - 推理请求中将其作为 `model` 传入
* `object`: 固定为 `model`
* `created`: 创建时间的 Unix 时间戳（秒）
* `owned_by`: 模型所属的供应商或组织
# 视频API使用示例和最佳实践 (/zh/api/video-examples)
本文档提供了zipflow视频生成API的完整使用示例和最佳实践指南。
## 完整使用流程示例 [#完整使用流程示例]
### 1. ZipFlow格式完整流程 [#1-zipflow格式完整流程]
```javascript
// 1. 生成视频
async function generateVideoWithZipFlow() {
const response = await fetch('https://api.zipflow.xyz/v1/video/generations', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'kling-v1',
prompt: '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级',
size: '1920x1080',
duration: 5,
metadata: {
seed: 20231234,
negative_prompt: '模糊, 低质量'
}
})
});
const result = await response.json();
return result.task_id;
}
// 2. 轮询查询状态
async function pollVideoStatus(taskId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/video/generations/${taskId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`视频生成失败: ${result.error?.message || '未知错误'}`);
}
// 等待后重试
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`第 ${attempt + 1} 次尝试失败:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('达到最大轮询次数');
}
// 3. 下载视频
async function downloadVideo(taskId) {
const response = await fetch(`https://api.zipflow.xyz/v1/videos/${taskId}/content`, {
headers: {
'Authorization': 'Bearer sk-xxxx'
}
});
if (!response.ok) {
throw new Error(`下载失败: ${response.statusText}`);
}
const blob = await response.blob();
return blob;
}
// 完整流程示例
async function completeVideoWorkflow() {
try {
// 生成视频
console.log('正在生成视频...');
const taskId = await generateVideoWithZipFlow();
console.log('任务ID:', taskId);
// 轮询状态
console.log('正在查询生成状态...');
const result = await pollVideoStatus(taskId);
console.log('视频生成完成:', result.url);
// 下载视频
console.log('正在下载视频...');
const videoBlob = await downloadVideo(taskId);
// 保存视频
const url = URL.createObjectURL(videoBlob);
const a = document.createElement('a');
a.href = url;
a.download = `video_${taskId}.mp4`;
a.click();
URL.revokeObjectURL(url);
console.log('视频下载完成');
} catch (error) {
console.error('流程失败:', error);
}
}
```
### 2. OpenAI兼容格式完整流程 [#2-openai兼容格式完整流程]
```javascript
// 1. 生成视频 (OpenAI格式)
async function generateVideoWithOpenAIFormat() {
const response = await fetch('https://api.zipflow.xyz/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'sora-2',
prompt: '一个穿着宇航服的宇航员在月球上行走, 高品质, 电影级',
seconds: '5',
size: '1920x1080'
})
});
const result = await response.json();
return result.id;
}
// 2. 查询状态 (OpenAI格式)
async function pollVideoStatusOpenAI(videoId, maxAttempts = 30) {
const baseUrl = 'https://api.zipflow.xyz';
const headers = {
'Authorization': 'Bearer sk-xxxx',
'Content-Type': 'application/json'
};
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const response = await fetch(`${baseUrl}/v1/videos/${videoId}`, {
headers
});
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new Error(`视频生成失败: ${result.error?.message || '未知错误'}`);
}
// 等待后重试
const delay = attempt < 6 ? 5000 : (attempt < 12 ? 10000 : 30000);
await new Promise(resolve => setTimeout(resolve, delay));
} catch (error) {
console.error(`第 ${attempt + 1} 次尝试失败:`, error);
if (attempt === maxAttempts - 1) {
throw error;
}
}
}
throw new Error('达到最大轮询次数');
}
```
## 不同模型的详细示例 [#不同模型的详细示例]
### 可灵AI (Kling) 示例 [#可灵ai-kling-示例]
```bash
# 文生视频
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v1",
"prompt": "一只橘猫在阳光下打盹，毛发蓬松，表情安详",
"duration": 5,
"metadata": {
"seed": 12345,
"negative_prompt": "模糊, 扭曲",
"cfg_scale": 0.8
}
}'
# 图生视频
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v2-master",
"image": "https://example.com/cat.jpg",
"prompt": "猫咪慢慢睁开眼睛，伸懒腰",
"duration": 3,
"metadata": {
"seed": 54321,
"negative_prompt": "快速动作",
"camera_control": {
"type": "simple",
"config": {
"horizontal": 1.0,
"vertical": 0,
"zoom": 0.5
}
}
}
}'
```
### 即梦 (Jimeng) 示例 [#即梦-jimeng-示例]
```bash
# 文生视频
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng_vgfm_t2v_l20",
"prompt": "海浪拍打着礁石，溅起白色的浪花",
"metadata": {
"req_key": "jimeng_vgfm_t2v_l20",
"aspect_ratio": "16:9",
"duration": 5
}
}'
# 图生视频
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng_vgfm_i2v_l20",
"image": "https://example.com/landscape.jpg",
"prompt": "云朵缓缓飘过天空",
"metadata": {
"req_key": "jimeng_vgfm_i2v_l20",
"image_urls": ["https://example.com/landscape.jpg"],
"aspect_ratio": "16:9"
}
}'
```
### Vidu 示例 [#vidu-示例]
```bash
curl -X POST https://api.zipflow.xyz/v1/video/generations \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-d '{
"model": "viduq1",
"prompt": "未来城市的夜景，霓虹灯闪烁",
"size": "1920x1080",
"duration": 5,
"metadata": {
"resolution": "1080p",
"movement_amplitude": "medium",
"bgm": true,
"seed": 0,
"callback_url": "https://your-callback-url.com/webhook"
}
}'
```
## 错误处理最佳实践 [#错误处理最佳实践]
### 1. 完整的错误处理示例 [#1-完整的错误处理示例]
```javascript
class VideoAPIClient {
constructor(apiKey, baseUrl) {
this.apiKey = apiKey;
this.baseUrl = baseUrl;
}
async generateVideo(params, format = 'zipflow') {
try {
const endpoint = format === 'openai' ? '/v1/videos' : '/v1/video/generations';
const response = await fetch(`${this.baseUrl}${endpoint}`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(params)
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
return await response.json();
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
throw new VideoAPIError(0, { message: error.message });
}
}
async pollStatus(taskId, format = 'zipflow', options = {}) {
const {
maxAttempts = 30,
initialDelay = 2000,
maxDelay = 30000
} = options;
let delay = initialDelay;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
const endpoint = format === 'openai'
? `/v1/videos/${taskId}`
: `/v1/video/generations/${taskId}`;
const response = await fetch(`${this.baseUrl}${endpoint}`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
}
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
const result = await response.json();
if (result.status === 'succeeded') {
return result;
} else if (result.status === 'failed') {
throw new VideoAPIError(400, {
message: result.error?.message || '视频生成失败'
});
}
// 等待后重试
await this.sleep(delay);
delay = Math.min(delay * 1.5, maxDelay);
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
console.error(`第 ${attempt + 1} 次轮询失败:`, error);
if (attempt === maxAttempts - 1) {
throw new VideoAPIError(0, { message: '轮询超时' });
}
}
}
}
async downloadVideo(taskId) {
try {
const response = await fetch(`${this.baseUrl}/v1/videos/${taskId}/content`, {
headers: {
'Authorization': `Bearer ${this.apiKey}`
}
});
if (!response.ok) {
const errorData = await response.json();
throw new VideoAPIError(response.status, errorData);
}
return await response.blob();
} catch (error) {
if (error instanceof VideoAPIError) {
throw error;
}
throw new VideoAPIError(0, { message: error.message });
}
}
sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
class VideoAPIError extends Error {
constructor(status, data) {
super(data.message || '未知错误');
this.status = status;
this.data = data;
this.name = 'VideoAPIError';
}
}
// 使用示例
async function exampleUsage() {
const client = new VideoAPIClient('sk-xxxx', 'https://api.zipflow.xyz');
try {
// 生成视频
const result = await client.generateVideo({
model: 'kling-v1',
prompt: '一只可爱的小狗在花园里玩耍',
duration: 5
});
console.log('任务创建成功:', result.task_id);
// 轮询状态
const status = await client.pollStatus(result.task_id, 'zipflow', {
maxAttempts: 20,
initialDelay: 3000
});
console.log('视频生成完成:', status.url);
// 下载视频
const videoBlob = await client.downloadVideo(result.task_id);
console.log('视频大小:', videoBlob.size);
} catch (error) {
if (error instanceof VideoAPIError) {
console.error(`API错误 (${error.status}):`, error.message);
} else {
console.error('未知错误:', error);
}
}
}
```
## 性能优化建议 [#性能优化建议]
### 1. 并发控制 [#1-并发控制]
```javascript
class VideoGenerationManager {
constructor(client, maxConcurrent = 3) {
this.client = client;
this.maxConcurrent = maxConcurrent;
this.running = 0;
this.queue = [];
}
async generateVideo(params) {
return new Promise((resolve, reject) => {
this.queue.push({ params, resolve, reject });
this.processQueue();
});
}
async processQueue() {
if (this.running >= this.maxConcurrent || this.queue.length === 0) {
return;
}
this.running++;
const { params, resolve, reject } = this.queue.shift();
try {
const result = await this.client.generateVideo(params);
const status = await this.client.pollStatus(result.task_id);
resolve(status);
} catch (error) {
reject(error);
} finally {
this.running--;
this.processQueue();
}
}
}
```
### 2. 缓存策略 [#2-缓存策略]
```javascript
class VideoCache {
constructor(ttl = 3600000) { // 1小时
this.cache = new Map();
this.ttl = ttl;
}
generateKey(params) {
return JSON.stringify(params);
}
get(params) {
const key = this.generateKey(params);
const cached = this.cache.get(key);
if (cached && Date.now() - cached.timestamp < this.ttl) {
return cached.result;
}
this.cache.delete(key);
return null;
}
set(params, result) {
const key = this.generateKey(params);
this.cache.set(key, {
result,
timestamp: Date.now()
});
}
clear() {
this.cache.clear();
}
}
```
## 监控和日志 [#监控和日志]
### 1. 性能监控 [#1-性能监控]
```javascript
class VideoAPIMonitor {
constructor() {
this.metrics = {
totalRequests: 0,
successfulRequests: 0,
failedRequests: 0,
averageResponseTime: 0,
errorTypes: new Map()
};
}
async measureTime(fn) {
const start = Date.now();
try {
const result = await fn();
this.recordSuccess(Date.now() - start);
return result;
} catch (error) {
this.recordFailure(Date.now() - start, error);
throw error;
}
}
recordSuccess(responseTime) {
this.metrics.totalRequests++;
this.metrics.successfulRequests++;
this.updateAverageResponseTime(responseTime);
}
recordFailure(responseTime, error) {
this.metrics.totalRequests++;
this.metrics.failedRequests++;
this.updateAverageResponseTime(responseTime);
const errorType = error.constructor.name;
this.metrics.errorTypes.set(
errorType,
(this.metrics.errorTypes.get(errorType) || 0) + 1
);
}
updateAverageResponseTime(responseTime) {
const total = this.metrics.totalRequests;
this.metrics.averageResponseTime =
(this.metrics.averageResponseTime * (total - 1) + responseTime) / total;
}
getMetrics() {
return {
...this.metrics,
successRate: this.metrics.totalRequests > 0
? this.metrics.successfulRequests / this.metrics.totalRequests
: 0
};
}
}
```
## 最佳实践总结 [#最佳实践总结]
### 1. API选择 [#1-api选择]
* **ZipFlow格式** (`/v1/video/generations`): 适合需要更多自定义参数的场景
* **OpenAI格式** (`/v1/videos`): 适合与OpenAI生态系统集成的场景
### 2. 错误处理 [#2-错误处理]
* 实现指数退避重试机制
* 区分临时错误和永久错误
* 提供有意义的错误信息
### 3. 性能优化 [#3-性能优化]
* 控制并发请求数量
* 实现适当的缓存策略
* 监控API调用性能
### 4. 用户体验 [#4-用户体验]
* 提供进度反馈
* 实现超时处理
* 支持取消操作
### 5. 资源管理 [#5-资源管理]
* 及时下载生成的视频
* 清理临时文件
* 监控存储使用情况
这些最佳实践可以帮助您构建稳定、高效的视频生成应用。
# Xinference 重排序格式（Rerank） (/zh/api/xinference-rerank)
在ZipFlow中，Xinference的rerank响应结构将被格式化为Jina的rerank响应结构，使用方式和Jina的rerank相同。**对于Dify等客户端用户**：在配置时请选择 **Jina AI** 作为供应商类型，而不是Xinference，并使用Xinference支持的模型名称。
## 📝 简介 [#-简介]
Xinference的重排序API与Jina AI的重排序API完全兼容。请参考[Jina AI 重排序格式（Rerank）](/zh/api/jinaai-rerank)文档了解详细的使用方法、请求参数和响应格式。
## 💡 使用方法 [#-使用方法]
使用Xinference重排序API时，只需将`model`参数设置为Xinference支持的重排序模型即可，其余参数和使用方式与Jina AI重排序API相同。
### 示例请求 [#示例请求]
```bash
curl https://api.zipflow.xyz/v1/rerank \
-H "Authorization: Bearer $ZIPFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jina-reranker-v2",
"query": "什么是美国的首都？",
"documents": [
"内华达州的首府是卡森城。",
"北马里亚纳群岛是太平洋上的一组岛屿，其首都是塞班岛。",
"华盛顿特区（也称为华盛顿或特区，正式名称为哥伦比亚特区）是美国的首都。",
"英语语法中的大写是在单词开头使用大写字母。英语用法与其他语言的大写不同。",
"自美国成为一个国家之前，美国就存在死刑。截至2017年，在50个州中有30个州死刑合法。"
],
"top_n": 3
}'
```
有关更多详细信息，请参考[Jina AI 重排序格式（Rerank）](/zh/api/jinaai-rerank)文档。