# Ace Data Cloud — Full Documentation > Unified AI API platform — LLM chat, image, video, music, and web-search APIs. One API key for 100+ AI services. This file inlines the full integration guide for every API so an LLM can ingest the entire documentation set in a single fetch. Base URL: `https://api.acedata.cloud` · Platform: https://platform.acedata.cloud · Docs: https://docs.acedata.cloud Concise API index: https://platform.acedata.cloud/llms.txt All requests use Bearer authentication (`Authorization: Bearer YOUR_API_TOKEN`) and return JSON. Many chat APIs are OpenAI-compatible — point the official OpenAI SDK at the base URL and set the model name. --- # Claude Code Configuration Tutorial Claude Code is a programming agent (Agentic Coding tool) launched by Anthropic, which can be used in terminals, various IDEs, and CI/CD pipelines such as GitHub Actions. Through the AceData Cloud proxy, you can use Claude Code at a lower price without an official Anthropic subscription, and a single API Token can call all services on the platform. ## Configuration Tutorial by Platform Choose the complete configuration tutorial for the corresponding platform based on your usage scenario: | Platform | Description | Tutorial Link | | ------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Terminal (CLI)** | Core experience, run `claude` in any terminal to get started | [Terminal Configuration Tutorial](https://platform.acedata.cloud/documents/claude-code-terminal-integration) | | **VS Code** | Native extension, supports inline Diff, @-mentions, scheduled reviews | [VS Code Configuration Tutorial](https://platform.acedata.cloud/documents/claude-code-vscode-integrations) | | **CC Switch (GUI)** | Desktop GUI, one-click vendor switch, no need to write configuration files | [CC Switch Configuration Tutorial](https://platform.acedata.cloud/documents/claude-code-cc-switch-integration) | | **GitHub Actions** | Automate code review and processing in Issues / PRs with `@claude` | [GitHub Actions Configuration Tutorial](https://platform.acedata.cloud/documents/claude-code-github-actions-integration) | ## General Configuration Regardless of the platform used, the core is to point the two environment variables of Claude Code to AceData Cloud: ```bash export ANTHROPIC_BASE_URL="https://api.acedata.cloud" export ANTHROPIC_AUTH_TOKEN="{token}" export CLAUDE_CODE_AUTO_COMPACT_WINDOW="850000" ``` Where `{token}` is the API Token you obtained from the [console](https://platform.acedata.cloud/console/applications); `CLAUDE_CODE_AUTO_COMPACT_WINDOW` sets the automatic compression trigger window to approximately 850,000 tokens, reserving space for tool results and final answers, and does not modify the model's context limit. The specific syntax for each platform (environment variables or `.claude/settings.local.json`, etc.) can be found in the corresponding tutorials above. > **Tip**: For first-time applicants, you can go to the [Claude Messages service page](https://platform.acedata.cloud/documents/claude-messages) and click "Acquire" to obtain credentials, which includes free credits; when credits are insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). --- # Codex Configuration Guide Codex CLI is an open-source local programming agent launched by OpenAI. It can read code, modify files, run commands, and assist with development tasks within the terminal. Through the Ace Data Cloud proxy, you can use Codex CLI at a lower cost without subscribing to an official OpenAI account separately. Choose the appropriate complete configuration tutorial based on your usage scenario: | Platform | Description | Tutorial Link | |----------|--------------|--------------| | **VS Code** | Official extension, enables chat, reference files, and preview diff in the editor sidebar | [VS Code Configuration Tutorial](https://platform.acedata.cloud/documents/codex-vscode-integration) | | **Terminal (CLI)** | Core experience, start by running `codex` in any terminal | [Terminal Configuration Tutorial](https://platform.acedata.cloud/documents/codex-terminal-integration) | > **Tip**: For the first application, you can go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain an API Token, which grants free credits. Codex CLI works through Ace Data Cloud's OpenAI Responses compatible interface (`/v1/responses`). For more models and billing information, refer to the [OpenAI Service Page](https://platform.acedata.cloud/documents/openai). --- # OpenCode Configuration Tutorial [OpenCode](https://opencode.ai) is an open-source terminal programming agent launched by the SST team, featuring "any model interchangeable, configuration file priority, TUI experience at your fingertips." It natively supports custom LLM providers, allowing seamless switching of model calls to Ace Data Cloud, enabling you to use models like Claude, GPT-5, Gemini, DeepSeek, etc., at a lower cost without needing to subscribe to separate accounts for each provider. Choose the corresponding complete configuration tutorial based on your usage scenario: | Platform | Description | Tutorial Link | | --------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | | **Terminal (CLI / TUI)** | Core experience, just run `opencode` in any terminal to get started | [Terminal Configuration Tutorial](https://platform.acedata.cloud/documents/mcp-tutorials-opencode) | | **MCP Service Access** | Call 11 remote MCP Servers from AceData within OpenCode | [OpenCode MCP Overview](https://platform.acedata.cloud/documents/opencode-mcp-all) | > **Tip**: First-time applicants can visit the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain an API Token, which includes free credits. OpenCode works through Ace Data Cloud's OpenAI Chat Completions compatible interface (`/v1/chat/completions`), and more model and billing information can be found on the [OpenAI Service Page](https://platform.acedata.cloud/documents/openai). --- # AceDataCloud Coding Plan Setup Center Coding Plan uses one Ace Data Cloud API Token across verified Claude Code, Codex CLI, WorkBuddy, VS Code, and compatible client surfaces, with free switching among Claude, GPT, GLM, Kimi, DeepSeek, and more. > Plus, Standard, Pro, and Max unlock the same complete model fleet. Plans differ only in included Credits. Thirty days is the validity of the Credits added by that purchase—not a model-unlock period. Coding Applications do not fall back to the general balance. ## Complete model fleet The live model directory keeps evolving. Current coverage includes: | Ecosystem | Representative models | Best for | |---|---|---| | Claude | Opus, Sonnet, Haiku | Large codebases, complex refactors, long tasks, code review | | GPT / Codex | Flagship and efficient GPT models | Codex agents, tool use, Responses workflows | | GLM | GLM 4.x / 5.x | Chinese development, daily coding, cost-efficient tasks | | Kimi | K2 / K3 families | Long context, repository understanding, planning and implementation | | DeepSeek | R1, V3, V4 families | Reasoning, algorithms, high-frequency efficient calls | Models are not gated by plan tier. After purchasing any plan, choose from the complete model directory in your client. Treat the real-time `/v1/models` response as authoritative. ## Claude Code ```bash export ANTHROPIC_BASE_URL="https://api.acedata.cloud" export ANTHROPIC_AUTH_TOKEN="YOUR_API_TOKEN" claude ``` Claude Code uses the Anthropic Messages protocol. Complete guides: - [Claude Code setup overview](https://platform.acedata.cloud/documents/claude-code-integration) - [Terminal setup](https://platform.acedata.cloud/documents/claude-code-terminal-integration) - [VS Code setup](https://platform.acedata.cloud/documents/claude-code-vscode-integrations) - [JetBrains setup](https://platform.acedata.cloud/documents/claude-code-jetbrains-integration) - [CC Switch setup](https://platform.acedata.cloud/documents/claude-code-cc-switch-integration) - [GitHub Actions setup](https://platform.acedata.cloud/documents/claude-code-github-actions-integration) ## Codex CLI ```bash export OPENAI_BASE_URL="https://api.acedata.cloud/v1" export OPENAI_API_KEY="YOUR_API_TOKEN" codex ``` Codex is the client entry point; it calls models from the GPT directory. Complete guides: - [Codex setup overview](https://platform.acedata.cloud/documents/codex-integration) - [Terminal setup](https://platform.acedata.cloud/documents/codex-terminal-integration) - [VS Code setup](https://platform.acedata.cloud/documents/codex-vscode-integration) - [CC Switch setup](https://platform.acedata.cloud/documents/codex-cc-switch-integration) ## WorkBuddy and Cursor compatibility WorkBuddy's custom model flow uses OpenAI Chat Completions. Keep **Custom protocol** off and enter the base URL below; WorkBuddy validates the address and appends the standard `/chat/completions` path: ```text Base URL: https://api.acedata.cloud/v1 API Key: YOUR_API_TOKEN ``` - [WorkBuddy setup](https://platform.acedata.cloud/documents/development_workbuddy) — verified custom-model setup - [Cursor compatibility](https://platform.acedata.cloud/documents/development_cursor_coding) — Cursor's current official BYOK documentation does not guarantee an arbitrary custom Base URL, so the selector does not generate Cursor configuration Model IDs change with the live directory. Use an exact model ID currently shown as compatible by the Coding selector instead of relying on a static list in this guide. ## Plans and Credits | Plan | Credits | Price | Credit validity | Model access | |---|---:|---:|---:|---| | Coding Plus | 200 | ¥99 | 30 days | Every model | | Coding Standard | 640 | ¥299 | 30 days | Every model | | Coding Pro | 1,500 | ¥699 | 30 days | Every model | | Coding Max | 4,000 | ¥1,399 | 30 days | Every model | Models consume Credits according to actual API usage. Standard input, output, cache writes, and cache reads are billed separately. Consumption changes with model, context, cache behavior, output, tools, and parallel tasks, so plan profiles guide selection and do not promise fixed hours, days, messages, or tasks. ## Choosing a billing model - If you only use Claude, interact heavily every day, and can work within five-hour and weekly allowances, Claude Max may offer better value. Heavy community cases report official API-equivalent usage far above the subscription price, but these are not fixed allowances or typical-user promises. - If you mainly use Kimi Code and Kimi consumer products and can work within shared monthly credits and five-hour/weekly controls, a Kimi membership may fit better. - If you need Claude, GPT/Codex, GLM, Kimi, and DeepSeek in one balance—or need APIs, automation, and per-call billing detail—Coding Plan fits better. Consumer memberships, official APIs, and Ace Credits are different billing models. Max 5x/20x and Kimi membership allowances cannot be converted into fixed Ace Credits, and Coding Plan does not promise universal savings. Coding Plan has no consumer-membership five-hour/weekly allowance reset, but normal API concurrency and rate limits still apply. ### Credit usage benchmark Anthropic's official Claude Code cost guide reports an industry benchmark of about $13 per developer per active day, with 90% of users below $30 per active day. Using the current uniform Opus 5 ratio across all four token buckets: | Plan | Like-for-like official API token value | $13 average active day | $30 high-intensity active day | Repeat-active sample coverage | |---|---:|---:|---:|---:| | Coding Plus · 200 Credits | about $95 | about 7 days | about 3 days | 56% | | Coding Standard · 640 Credits | about $304 | about 23 days | about 10 days | Everyday full-time tier | | Coding Pro · 1,500 Credits | about $713 | about 55 days | about 24 days | 80% | | Coding Max · 4,000 Credits | about $1,903 | about 146 days | about 63 days | 90% | An active day only means Claude Code API usage occurred that day; it is not a fixed number of hours, messages, or tasks. Platform coverage uses an anonymized 28-day sample of 41 repeat-active users and is directional because the sample is small. Plus is therefore an occasional personal tier, Standard an everyday full-time tier, Pro a full-time high-intensity tier, and Max a Fleet/team tier. One person will usually not consume Max within 30 days; large parallel fleets, unattended pipelines, or near-24/7 workloads should use Max, metered balance, or an enterprise plan. ## Choosing a model - Large refactors, cross-file analysis, and long agent tasks: start with Claude Opus or Sonnet. - Codex CLI, Responses toolchains, and OpenAI SDKs: choose a GPT model. - Chinese projects and cost-efficient daily coding: try GLM. - Very long context, requirements, and repository planning: try Kimi. - Algorithmic reasoning, high-frequency work, and cost-sensitive tasks: try DeepSeek. ## Troubleshooting ### Insufficient balance Open the [Applications console](https://platform.acedata.cloud/console/applications), find the Coding Application, and purchase again. Coding balance never falls back to the general balance. ### The client still calls its original endpoint Confirm the environment variables are set in the same terminal session that launches the client, then fully quit and restart it. ### A model name is unavailable Request `GET https://api.acedata.cloud/v1/models` for the live directory. Do not use Codex as a model ID: Codex is the client, and GPT models are selected after setup. ### The token cannot call an endpoint Confirm the credential belongs to the Coding Application and inspect its API scope. Coding Plan supports Claude Messages, Count Tokens, OpenAI Chat Completions, and OpenAI Responses. --- # Ace Data Cloud SDK Overview Ace Data Cloud provides official client SDKs in TypeScript / Python / Go, encapsulating the capabilities of chat completions, images, video, music, search, x402, etc., on `api.acedata.cloud` into strongly typed methods, saving the effort of manually handling HTTP, SSE, task polling, error handling, and retry backoff. This chapter is organized in the order of actual integration: first obtain the API Token from the console, then select the language to view the corresponding section, and finally look at advanced usage of task polling, streaming responses, and X402 on-chain payments. ## Repositories and Packages - SDK Source Code (monorepo): [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) - TypeScript: [`@acedatacloud/sdk`](https://www.npmjs.com/package/@acedatacloud/sdk) - Python: [`acedatacloud`](https://pypi.org/project/acedatacloud/) - Go: [`github.com/AceDataCloud/SDK/go`](https://pkg.go.dev/github.com/AceDataCloud/SDK/go) - X402 Client (TypeScript): [`@acedatacloud/x402-client`](https://www.npmjs.com/package/@acedatacloud/x402-client) - X402 Client (Python): [`acedatacloud-x402`](https://pypi.org/project/acedatacloud-x402/) ## Capability Matrix for Three Languages | Capability | TypeScript | Python | Go | | ------------------------------------------------------------ | ----------- | ----------------------- | --------------------- | | `chat.completions.create` (non-streaming) | ✅ | ✅ | ✅ | | `chat.completions.create` (SSE streaming) | ✅ | ✅ | ✅ | | `images.generate` (Midjourney / Flux / NanoBanana / Seedream) | ✅ | ✅ | 🚧 (alpha) | | `videos.generate` (Sora / Veo / Luma / Kling / Hailuo / Wan) | ✅ | ✅ | 🚧 (alpha) | | `audios.generate` (Suno / Producer / Fish) | ✅ | ✅ | 🚧 (alpha) | | `search.google` (Serp) | ✅ | ✅ | 🚧 (alpha) | | TaskHandle asynchronous polling | ✅ (milliseconds) | ✅ (seconds) | 🚧 | | Asynchronous client | ✅ (Promise) | ✅ (`AsyncAceDataCloud`) | ✅ (`context.Context`) | | Automatic retry + exponential backoff | ✅ | ✅ | ✅ | | Typed exceptions (`AuthenticationError` / `RateLimitError` …) | ✅ | ✅ | ✅ | | X402 `paymentHandler` hook (on-chain payment without token) | ✅ | ✅ | ❌ (planned) | > The multimedia resources and task polling of the Go SDK are currently in alpha (pseudo version `v0.0.0-20260505072132-4a3d921f9bb4`), with stable capabilities being `chat.completions`. For multimedia scenarios, please prioritize TypeScript or Python. ## When to Use SDK / MCP / Native HTTP / X402 | Scenario | Recommended Method | | ------------------------------------------- | ---------------------------------------------------------------------- | | Backend services, CLI, automation scripts, Agent frameworks | **SDK** (this chapter) | | MCP client calls like Claude Desktop / Cursor / Cline | MCP Servers | | One-time curl verification, debugging, embedded environments that only support HTTP | Native HTTP (Quick Start for each service) | | Do not want to create an API Token, pay USDC on the call chain | [X402 Integration Guide](https://platform.acedata.cloud/documents/x402-integration) | SDK and X402 are not mutually exclusive: the SDK supports both "token path" and "`paymentHandler` path", see [SDK + X402 Payment Hook](https://platform.acedata.cloud/documents/sdk-x402-payment). ## Applying for API Token To use the SDK, first apply for an API Token at [Ace Data Cloud Console - Application List](https://platform.acedata.cloud/console/applications): ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after logging in or registering, you will be automatically returned to the current page. You will receive a free quota upon your first application, allowing you to experience various AI services provided by Ace Data Cloud for free. Copy the Token you just obtained, which will be referred to as `{token}` below. ## Unified Environment Variable The SDKs in the three languages will automatically read the same environment variable `ACEDATACLOUD_API_TOKEN`, and it is recommended to `export` it in the shell, allowing the SDK to pick it up automatically: ```bash export ACEDATACLOUD_API_TOKEN={token} # Optional: default https://api.acedata.cloud # export ACEDATACLOUD_BASE_URL=https://api.acedata.cloud ``` You can also explicitly pass it when constructing the client, with the corresponding parameter names for the three languages being: - TypeScript: `new AceDataCloud({ apiToken: '{token}' })` - Python: `AceDataCloud(api_token="{token}")` - Go: `adc.NewClient(adc.WithAPIToken("{token}"))` > Note: The AceDataCloud project repository conventionally uses `ACEDATACLOUD_API_KEY` (in `.env` / CI), but these three SDKs only recognize `ACEDATACLOUD_API_TOKEN`. If your environment only has `ACEDATACLOUD_API_KEY`, please explicitly pass it during construction. ## 30 Seconds to Get Started with Three Examples The following three code snippets do the same thing: call `gpt-4o-mini` and have it reply with `ADC_*_OK` exactly. Each snippet includes **actual running results**, which you can reproduce with your own token. ### TypeScript ```ts import { AceDataCloud } from '@acedatacloud/sdk'; const client = new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY }); const t0 = Date.now(); const res = await client.openai.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: 'Reply with exactly: ADC_TS_SDK_OK' }], max_tokens: 20, temperature: 0 }); console.log('elapsed_ms', Date.now() - t0); console.log('id', res.id); console.log('model', res.model); console.log('content', res.choices[0].message.content); console.log('usage', JSON.stringify(res.usage)); ``` > The SDK currently declares the response as `Record`, and at runtime, it is a regular JSON object that can be accessed directly by fields. In strict TS projects, if you encounter type errors, you can temporarily use `as any`, or refer to [SDK Task Polling and Streaming Responses](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) to create a custom typed wrapper. Program running result: ```text elapsed_ms 2543 id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQA model gpt-4o-mini content ADC_TS_SDK_OK usage {"prompt_tokens":16,"completion_tokens":6,"total_tokens":22} ``` ### Python ```python import os, time, json from acedatacloud import AceDataCloud client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"]) t0 = time.time() res = client.openai.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_SDK_OK"}], max_tokens=20, temperature=0, ) print("elapsed_ms", int((time.time() - t0) * 1000)) print("id", res["id"]) print("model", res["model"]) print("content", res["choices"][0]["message"]["content"]) print("usage", json.dumps({k: v for k, v in res["usage"].items() if k in ("prompt_tokens","completion_tokens","total_tokens")})) ``` > The current return of the Python SDK is `dict`, so use `res["id"]` instead of `res.id`. This is different from `openai-python`, so be careful during migration. Program running result: ```text elapsed_ms 2963 id chatcmpl-DldFdnIlhSUXINpupgsUmZL78MnBu model gpt-4o-mini content ADC_PY_SDK_OK usage {"prompt_tokens": 17, "completion_tokens": 7, "total_tokens": 24} ``` ### Go ```go package main import ( "context" "fmt" "os" "time" adc "github.com/AceDataCloud/SDK/go" ) func main() { client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_KEY"))) if err != nil { panic(err) } ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second) defer cancel() t0 := time.Now() res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{ Model: "gpt-4o-mini", Messages: []map[string]any{{"role": "user", "content": "Reply with exactly: ADC_GO_SDK_OK"}}, MaxTokens: 20, }) if err != nil { panic(err) } fmt.Println("elapsed_ms", time.Since(t0).Milliseconds()) fmt.Println("id", res["id"]) fmt.Println("model", res["model"]) choices := res["choices"].([]any) msg := choices[0].(map[string]any)["message"].(map[string]any) fmt.Println("content", msg["content"]) usage := res["usage"].(map[string]any) fmt.Printf("usage prompt=%v completion=%v total=%v\n", usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"]) } ``` > The Go SDK response is uniformly `map[string]any`, without strong typed struct, requiring manual type assertion. All resource accessors are method chains: `client.OpenAI().Chat().Completions().Create(...)`. Program running result: ```text elapsed_ms 6436 id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv model gpt-4o-mini content ADC_GO_SDK_OK usage prompt=16 completion=5 total=21 ``` The `id`, `elapsed_ms`, and `usage` in the responses of the three languages come from the same source: authenticated by PlatformGateway → upstream OpenAI compatible service → written into billing records. The `content` field is the actual output of the model, using a fixed identifier `ADC_*_OK` to prove that the response has not been tampered with by the SDK. ## Recommended Reading Order 1. [TypeScript SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-typescript) —— Code that can run after `npm install`. 2. [Python SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-python) —— Three sets of usage: synchronous, asynchronous, and streaming. 3. [Go SDK Integration Tutorial](https://platform.acedata.cloud/documents/sdk-go) —— Go-style `context.Context` and channel streaming. 4. [SDK Task Polling and Streaming Response](https://platform.acedata.cloud/documents/sdk-tasks-and-streaming) —— Differences in TaskHandle units, SSE implementation details, and retry backoff. 5. [SDK + X402 Payment Hook](https://platform.acedata.cloud/documents/sdk-x402-payment) —— No token, on-chain settlement based on calls. ## How to Check Remaining Quota You can check the current account's remaining quota through the [Ace Data Cloud Console - Application List](https://platform.acedata.cloud/console/applications). You can view all usage history and billing details through the [Ace Data Cloud Console - Usage History](https://platform.acedata.cloud/console/usages). ## Learn More - 📦 [SDK monorepo source code](https://github.com/AceDataCloud/SDK) - 🔌 [X402 Integration Guide](https://platform.acedata.cloud/documents/x402-integration) - 🛠 MCP Servers Tutorial - 📊 [Service List and Pricing](https://platform.acedata.cloud/services) --- # Access "Login with Ace Data Cloud" (OAuth 2.0) Enable your product to support "Login with Ace Data Cloud" and, after user authorization, **act on behalf of the user** to read and write their Ace Data Cloud resources (profile, API Token, subscriptions, usage, orders, etc.). The underlying mechanism is the standard **OAuth 2.0 Authorization Code Flow + PKCE**, which is completely consistent with the login methods of GitHub / Google — any existing OAuth client library you have can be used directly. > **Suitable Scenarios**: You are developing a third-party application / Agent / MCP client / automation workflow and want users to log in with their Ace Data Cloud account with one click, accessing their resources on the platform as needed, without requiring users to manually copy and paste the API Key. ## Terminology & Endpoint Quick Reference All endpoints are at `https://auth.acedata.cloud`, and you can always get the latest address through the discovery endpoint: ```bash curl https://auth.acedata.cloud/.well-known/oauth-authorization-server ``` | Purpose | Endpoint | | ---------------------- | --------------------------------------------------- | | Discovery Document | `GET /.well-known/oauth-authorization-server` | | User Authorization Page (Browser Redirect) | `GET https://auth.acedata.cloud/oauth2/authorize` | | Token Endpoint (Exchange / Refresh token) | `POST https://auth.acedata.cloud/oauth2/token` | | Revoke Token | `POST https://auth.acedata.cloud/oauth2/revoke` | | User Information (UserInfo) | `GET https://auth.acedata.cloud/api/v1/users/me` | | Application Registration Management (Self-service) | `https://auth.acedata.cloud/user/oauth-apps` | Supported capabilities: `response_type=code`, `grant_types=authorization_code, refresh_token`, `code_challenge_methods=S256, plain`, client authentication methods `client_secret_post` (confidential client) / `none` (PKCE public client). ## Permission Scope (Scope) Apply for "least privilege," and users will see each permission you request on the authorization page. **Identity (OIDC Compatible)** | Scope | Meaning | `/users/me` Return Fields | | --------- | ------- | ---------------------------------------------------------- | | `openid` | User unique identifier | `id` | | `profile` | Basic information | `username`, `nickname`, `avatar`, `is_verified`, `date_joined` | | `email` | Email | `email` | | `phone` | Phone number (sensitive) | `phone`, `region` | **Platform Resource** | Scope | Meaning | | ------------------------------------------ | ---------------------- | | `applications:read` / `applications:write` | Read / Modify user service subscriptions and quotas | | `credentials:read` / `credentials:write` | Read / Create Revoke user API Token | | `usage:read` | Read user call history | | `orders:read` / `orders:write` | Read orders / Place orders and initiate payment | **Aggregation (Automatically Expanded)** | Scope | Expanded To | | ---------------- | ----------------------------------------------------------------------- | | `platform:read` | `applications:read` + `credentials:read` + `usage:read` + `orders:read` | | `platform:write` | `applications:write` + `credentials:write` + `orders:write` | | `platform` | `platform:read` + `platform:write` | **Special** | Scope | Meaning | | ---------------- | -------------------------------------------------- | | `offline_access` | Issue **Refresh Token** (if not requested, only Access Token is issued, and re-authorization is required when it expires) | > Typical combinations: Third-party "one-click login" = `openid profile`; MCP / IDE client needs to automatically configure Key = `openid profile credentials:read credentials:write`; Full management console = `openid profile email platform offline_access`. ## Step 1: Register an OAuth Application Open [auth.acedata.cloud/user/oauth-apps](https://auth.acedata.cloud/user/oauth-apps) → "Create Application," fill in: 1. **Application Name / Description / Logo**: Will be displayed on the user's authorization consent page. 2. **Client Type**: - **Confidential** — You have a backend that can securely store `client_secret` (Web service, backend service). - **Public** — Pure frontend / desktop / CLI / mobile, **cannot** store secrets, must use **PKCE**. 3. **Redirect URIs**: The address to which users are redirected after authorization is complete, **must exactly match the `redirect_uri` you passed when initiating authorization**, can fill in multiple. 4. **Permission Scope (Scopes)**: Check the scopes you need from the previous section. After saving, obtain **`client_id`**; confidential clients will also **once** display **`client_secret`**—save it immediately, as it cannot be viewed again after closing (can be regenerated on the details page under "Rotate Secret," and the old secret will become invalid immediately). > Each account can create a maximum of **20** OAuth applications. ## Step 2: Redirect the User to the Authorization Page In your application, redirect the user's browser to the authorization page with the query parameters: ``` https://auth.acedata.cloud/oauth2/authorize ?response_type=code &client_id= &redirect_uri= &scope=openid%20profile%20credentials:read &state= &code_challenge= # Required for public clients &code_challenge_method=S256 # Required for public clients ``` - `state`: A randomly generated string that is returned as is during the callback, used for CSRF protection, **must be validated**. - **PKCE (mandatory for public clients, recommended for confidential clients)**: First generate a random `code_verifier`, then calculate `code_challenge = BASE64URL( SHA256( code_verifier ) )`, place the `code_challenge` in the authorization URL, keep the `code_verifier` for use in Step 4. After the user logs in and clicks "Agree," the browser will be redirected back to: ``` ?code=&state= ``` If the user declines: `?error=access_denied&error_description=...&state=...`. > The authorization code is valid for **10 minutes** and **can only be used once**. ## Step 3: Exchange the Authorization Code for a Token In your **backend** (confidential client) or client (PKCE public client), call the token endpoint using the `code`. **Confidential Client (with client_secret):** ```bash curl -X POST https://auth.acedata.cloud/oauth2/token \ -d grant_type=authorization_code \ -d code= \ -d client_id= \ -d client_secret= \ -d redirect_uri= ``` **Public Client (PKCE, without client_secret):** ```bash curl -X POST https://auth.acedata.cloud/oauth2/token \ -d grant_type=authorization_code \ -d code= \ -d client_id= \ -d code_verifier= \ -d redirect_uri= ``` Successful response (the `refresh_token` only appears when `offline_access` is requested): ```json { "access_token": "", "token_type": "Bearer", "expires_in": 1296000, "scope": "openid profile credentials:read", "refresh_token": "" } ``` `access_token` is a JWT that contains the `scope` claims; valid for **15 days** (`expires_in` in seconds). The Refresh Token is valid for **30 days**. ## Step 4: Call the API with the Access Token Place the token in the `Authorization: Bearer` header. **Read User Information (UserInfo, fields filtered by authorized scope):** ```bash curl https://auth.acedata.cloud/api/v1/users/me \ -H "Authorization: Bearer " ``` **Call Platform Resource API** (`api.acedata.cloud`, authorized by scope). For example, if `credentials:read` is granted: ```bash curl https://api.acedata.cloud/api/v1/credentials/ \ -H "Authorization: Bearer " ``` The platform backend will validate the `scope` claims in the JWT—tokens can only access resources authorized by the user. If unauthorized resources are accessed, a `403` will be returned. ## Refresh Token After the Access Token expires, use the Refresh Token to obtain a new pair of tokens (requires that `offline_access` was initially requested): ```bash curl -X POST https://auth.acedata.cloud/oauth2/token \ -d grant_type=refresh_token \ -d refresh_token= ``` The return structure is the same as in step 3; the scope will be **retained as is** from the original authorization. The old Refresh Token becomes invalid (rotated) after refreshing, please save the new one. ## Revoke Token ```bash curl -X POST https://auth.acedata.cloud/oauth2/revoke \ -d token= ``` ## Real Case: This is how our own MCP server connects The 15+ MCP servers of Ace Data Cloud (NanoBanana, Midjourney, Suno, Seedance, Kling…) that appear in Claude Desktop / Cursor with the "Sign in with Ace Data Cloud" link follow this process: they are all registered as **public (PKCE)** type OAuth applications, requesting `credentials` related scopes. After user authorization, the MCP server can call `api.acedata.cloud` on behalf of the user—without the user manually pasting the API Key. Your connection method is exactly the same as theirs. ## Common Errors Error responses are uniformly formatted as `{ "error": "", "error_description": "" }`: | error | Meaning / Troubleshooting | | ------------------------ | --------------------------------------------------------------- | | `invalid_request` | Missing or illegal parameters (e.g., did not send `code` / `client_id`) | | `invalid_client` | `client_id` does not exist, application is disabled, or `client_secret` is incorrect | | `invalid_grant` | Authorization code does not exist / has expired (>10 minutes) / has been used / PKCE verification failed / `redirect_uri` does not match the authorization | | `access_denied` | User clicked "Deny" on the authorization page | | `unsupported_grant_type` | `grant_type` is not `authorization_code` or `refresh_token` | ## Rate Limits | Item | Value | | ------------------- | ------------------------------- | | Maximum number of OAuth applications per account | 20 | | Authorization code validity period | 10 minutes, single use | | Access Token validity period | 15 days | | Refresh Token validity period | 30 days (rotated) | | `redirect_uri` | Must match the registered value exactly | | `client_secret` | Displayed only once during creation / rotation, stored on the server as SHA-256 hash | --- # X402 Integration Guide X402 is an on-chain payment protocol based on HTTP `402 Payment Required`. With the X402 capabilities of Ace Data Cloud, callers can complete on-chain payments directly with USDC in each API request without creating an API Token or pre-funding account balances. This set of documents is organized in the order of actual integration: first run through a minimal request, then integrate the SDK, and finally understand networks, billing schemes, order payments, and Facilitator. It is recommended to read from top to bottom as per the table below. | Tutorial | Applicable Scenarios | Link | | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Quick Start | Understand the 402, `accepts`, and `PAYMENT-SIGNATURE` process with a minimal request | [X402 Quick Start](https://platform.acedata.cloud/documents/x402-quickstart) | | TypeScript SDK | Call Ace Data Cloud API in browsers, Node.js, or front-end applications | [TypeScript SDK Integration](https://platform.acedata.cloud/documents/x402-typescript-sdk) | | Python SDK | Call the API in Python services, scripts, Agents, or data pipelines | [Python SDK Integration](https://platform.acedata.cloud/documents/x402-python-sdk) | | Order Payment | Use X402 to pay for Ace Data Cloud console orders | [Order Payment Tutorial](https://platform.acedata.cloud/documents/x402-order-payment) | | Networks and Payment Methods | Understand assets, signatures, and applicable scenarios for Base, SKALE, and Solana | [Networks and Payment Methods](https://platform.acedata.cloud/documents/x402-networks) | | `exact` and `upto` | Distinguish between fixed-price APIs and usage-based billing APIs | [Billing Scheme Explanation](https://platform.acedata.cloud/documents/x402-metered-upto) | | Pricing Explanation | Understand the relationship between X402 pricing and Credits unit price, and the actual prices of various services | [X402 Pricing Explanation](https://platform.acedata.cloud/documents/x402-pricing) | | Facilitator | Understand the server-side link of `verify`, `settle`, and self-built payment APIs | [Facilitator Integration](https://platform.acedata.cloud/documents/x402-facilitator) | | E2E and Troubleshooting | Check public entry points, run advanced validation tools, and locate common 402, signature, and settlement issues | [E2E Validation and Troubleshooting](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) | ## Recommended Integration Path If you just want to call the Ace Data Cloud API, it is recommended to use the official SDKs: - TypeScript: `@acedatacloud/sdk` + `@acedatacloud/x402-client` - Python: `acedatacloud` + `acedatacloud-x402` Public source code and package addresses: | Project | Address | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | Ace Data Cloud SDK | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) | | X402 Client | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) | | X402 Facilitator | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) | | npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) | | npm X402 Client | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) | | PyPI SDK | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) | | PyPI X402 Client | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) | The SDK will automatically handle the first unauthenticated request, parse `402 Payment Required`, call the payment handler, and retry these steps with `PAYMENT-SIGNATURE`. You only need to prepare a wallet with USDC and choose the network you wish to use. If you want your own API to also support X402 payments, you will need to read the Facilitator documentation to understand the relationship between `paymentRequirements`, `paymentPayload`, `/verify`, and `/settle`. ## Support Status Ace Data Cloud X402 has been validated in public APIs, official SDKs, Facilitator, and on-chain settlement paths. The table below summarizes the current status based on the most commonly used capabilities by developers during integration. | Capability | Status | Description | | ------------------ | --------------------- | ------------------------------------------------------------------------- | | 402 discovery | Available | `https://x402.acedata.cloud/.well-known/x402` returns the public discovery document. | | API 402 `accepts` | Available | Unpaid requests will return available payment requirements for Base, SKALE, and Solana. | | TypeScript SDK | Available | `@acedatacloud/sdk` and `@acedatacloud/x402-client` can automatically handle 402, signatures, and retries. | | Python SDK | Available | `acedatacloud` and `acedatacloud-x402` can automatically handle 402, signatures, and retries. | | Base `exact` | On-chain validated | Suitable for fixed amount APIs and order payments. | | Base `upto` | On-chain validated | Suitable for post-measurement APIs like chat completion; currently the only network providing `upto`. | | SKALE `exact` | On-chain validated | Suitable for low gas cost EVM payment scenarios. | | Solana `exact` | HTTP paid retry validated | Validated API paid retry with model response; on-chain signature confirmation is recommended to use your own Solana RPC for reconciliation. | | Order Payment | On-chain validated | Base `exact` order payments have completed on-chain settlement and updated order status. | The following output is for illustrative purposes only to show the return format of validated paths. During actual integration, always refer to the current API's returned `accepts`. ```text packages @acedatacloud/sdk@2026.504.2 import ok @acedatacloud/x402-client@2026.531.3 import ok acedatacloud==2026.4.26.1 import ok acedatacloud-x402==2026.5.31.3 import ok API 402 status 402 accepts eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact TypeScript SDK content ADC_TS_SDK_X402_OK Python SDK content ADC_PY_SDK_X402_OK Base exact content ADC_BASE_E2E_OK tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 SKALE exact content ADC_SKALE_E2E_OK tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f Base upto content ADC_BASE_UPTO_OK tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 signed ceiling 95215 atomic USDC transfer value 3 atomic USDC Solana exact HTTP 402 -> HTTP 200 content ADC_SOLANA_E2E_OK chain signature not confirmed in this run Order payment order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402 tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 ``` Note: - npm and PyPI packages have been successfully installed and imported in a clean environment. - Unpaid API requests return 402, and the `accepts` includes available payment methods for Base, SKALE, and Solana. - `accepts[].network` is a CAIP-2 identifier, and clients must match the CAIP-2 string when selecting a network. - Both TypeScript SDK and Python SDK can automatically handle 402 and complete paid retry. - Base `exact`, SKALE `exact`, Base `upto`, and order payments all have publicly accessible explorer addresses. - The signature ceiling for Base `upto` is `95215` atomic USDC, with an actual settlement of `3` atomic USDC, reflecting the characteristic of post-measurement settlement based on actual usage. - Solana `exact` has verified HTTP 402 -> HTTP 200 and model output. Due to potential rate limiting on public RPC queries, it is recommended to use a private Solana RPC or platform-side settlement records to confirm transaction signatures during strict reconciliation. ## Access Considerations When integrating, developers should prioritize the real-time payment requirements returned by the current request, rather than copying example amounts or addresses from the documentation: - `accepts[].maxAmountRequired` is the maximum amount that can be signed for the current request. - `accepts[].asset` is the USDC contract or mint to be used for this request. - `accepts[].extra.chainId`, `accepts[].extra.facilitatorAddress`, and `accepts[].extra.verifyingContract` will participate in EVM typed data signing. - `upto` requires the wallet to first authorize Permit2 for the target chain USDC; if not authorized, it will return `PERMIT2_ALLOWANCE_REQUIRED`. - If you explicitly wish to use post-measurement, please pass `preferScheme: 'upto'` in the TypeScript SDK; otherwise, the SDK will select the first available requirement returned by the server under that network. ## Public Verification Scope Before integration, you can verify these public endpoints and SDK behaviors: - API requests without `Authorization` or `PAYMENT-SIGNATURE` will return `402 Payment Required`, and the `accepts` in the response is the only signature basis for this request. - Both TypeScript SDK and Python SDK provide a payment handler, and the SDK transport layer will call the handler and retry once upon receiving a 402. - `https://x402.acedata.cloud/.well-known/x402`: returns the X402 discovery document and specification resource addresses. - `https://facilitator.acedata.cloud/supported`: returns the networks and schemes supported by the Facilitator. - The X402Client repository contains advanced on-chain verification tools that can be used to confirm signatures, retries, and settlement behaviors; tool outputs do not replace the `accepts` returned by the online API. `upto` belongs to post-measurement settlement, suitable for APIs where actual usage is only known after the response, such as chat completion and model calls. Currently, only Base provides `upto`; if signature verification fails, please check whether the chain id, facilitator address, spender, USDC contract, and Permit2 allowance are consistent with the 402 response. --- # Using Ace Data Cloud in AnythingLLM [AnythingLLM](https://anythingllm.com/) is an open-source client positioned as "Document → Private ChatGPT," with the core concept being **Workspace**—each Workspace is a set of documents, a group of users, and a set of Agent tools, independently isolated. It is designed specifically for document conversations and provides both a desktop app and Docker deployment. Among **LLM providers**, it has a built-in option for [OpenAI (Generic)](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic), which allows for a custom Base URL, enabling direct pointing of the conversation model to Ace Data Cloud. This article describes the configuration process. ## Application Process To integrate Ace Data Cloud into AnythingLLM, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Download AnythingLLM For personal use, you can download the [desktop version](https://anythingllm.com/download), where the vector database (LanceDB) runs locally, allowing document searches to be completely offline, with internet access only when calling the model; for team multi-user scenarios, use [Docker deployment](https://docs.anythingllm.com/installation-docker/overview). ## Configure the Conversation Model Start AnythingLLM, go to **Settings → LLM Preference**, and select **OpenAI (Generic)** as the Provider (do not select the regular OpenAI, as that points to `api.openai.com` without a custom Base URL). Refer to the official documentation for [OpenAI (Generic) LLM Provider](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic). | Field | Value | Description | | --------------------- | --------------------------------- | --------------------------------------- | | Base URL | `https://api.acedata.cloud/v1` | **Must end with `/v1`** | | API Key | Your Ace Data Cloud Token | Token copied from the console | | Selected Model | `gpt-5` | Dropdown, automatically pulled from the endpoint `/models`; if not returned, fallback to manual input | | Model context window | `128000` | Context window size (there's also a Max Tokens field next to it) | Note the path rules for Base URL: | Base URL | Actual Request | Result | | -------------------------------------- | ------------------------------------------------------ | ---------------------------- | | `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | Also usable | | `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (`/openai` does not have `/v1`) | | `https://api.acedata.cloud` | `https://api.acedata.cloud/chat/completions` | 404 (missing `/v1`) | ## Configure the Embedding Model The core of AnythingLLM is RAG, which requires an embedding model to vectorize documents. Its **Embedding Preference** is a separate configuration from LLM Preference—see [Embedder Configuration Overview](https://docs.anythingllm.com/setup/embedder-configuration/overview). The built-in **AnythingLLM Embedder (Built-in / Native)** runs directly on the local machine, is ready to use out of the box, and requires zero configuration, making it the default and recommended choice: Go to **Settings → Embedding Preference**, and keep the Provider as the default **AnythingLLM Embedder**, without needing to fill in any keys. It will complete document vectorization locally, with both the original text and vectors stored in the local LanceDB, not going to the cloud. > The candidates for AnythingLLM's Embedder (cloud: OpenAI / Azure OpenAI / Cohere; local: Built-in, LM Studio, [LocalAI](https://docs.anythingllm.com/setup/embedder-configuration/local/localai), Ollama) are all integrated in their respective fixed forms. Among them, the cloud OpenAI embedding points to `api.openai.com` and does not support custom Base URLs; if you wish to use a custom endpoint, you can use the **Generic OpenAI** Embedder (which also has a Base URL field that can point to Ace Data Cloud's `text-embedding-3-large`) or the local **LocalAI** Embedder. This article uses Ace Data Cloud for the conversation model and the built-in local Embedder for embedding, with no interference between the two. ## Recommended Models The following conversation model IDs can be filled in the Selected Model field in AnythingLLM's OpenAI (Generic) Provider: | Family | Model ID | Notes | | --------- | ------------------------------------------ | -------------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview`| Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | For a complete list of models and their availability, please refer to the [Ace Data Cloud Service Documentation](https://platform.acedata.cloud/documents). ## Verify Integration If you are unsure whether the issue lies with AnythingLLM or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: Workspace and Document Conversations After creating a Workspace, upload PDF / Word / Markdown and other documents. AnythingLLM will split them by paragraphs, generate vectors using the local Embedder, and store them in the local LanceDB. During conversations, it will first retrieve relevant segments and then pass those segments along with your questions to the dialogue model (i.e., Ace Data Cloud) for answers, marking the source of the citations below the responses. At the top of each Workspace, you can switch between **Query** (answers based solely on documents) and **Chat** (mixed general knowledge) modes. In serious scenarios, it is recommended to use Query mode to avoid hallucinations. When deploying with Docker, you can use environment variables like `GENERIC_OPEN_AI_BASE_PATH`, `GENERIC_OPEN_AI_API_KEY`, `GENERIC_OPEN_AI_MODEL_PREF`, etc., to preset the same dialogue model access and enable multi-user mode. ## Frequently Asked Questions ### Prompt 404 / connection fail This is usually because the Base URL is written as `.../openai/v1` or is missing `/v1`. Change it to `https://api.acedata.cloud/v1`. ### Unable to converse after uploading documents Please confirm that a usable Embedder is selected in **Settings → Embedding Preference** (the default AnythingLLM Embedder can run locally without additional configuration), and re-upload the documents to generate vectors. ### Prompt 401 Unauthorized Please confirm that the API Key pasted is the Token from Ace Data Cloud (without the `Bearer ` prefix and no extra spaces), and that the balance of the associated application is sufficient. ### Will local documents be uploaded to the cloud? No. The original text of the documents exists in the local LanceDB, and only the segments that match the retrieval with your questions will be sent to the model. ## Learn More - [AnythingLLM Official Website](https://anythingllm.com/) ｜ [AnythingLLM GitHub](https://github.com/Mintplex-Labs/anything-llm) ｜ [Docker Deployment Documentation](https://docs.anythingllm.com/installation-docker/overview) - [AnythingLLM OpenAI (Generic) LLM Provider Documentation](https://docs.anythingllm.com/setup/llm-configuration/cloud/openai-generic) - [AnythingLLM Embedder Configuration Overview](https://docs.anythingllm.com/setup/embedder-configuration/overview) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in ChatBox [ChatBox](https://chatboxai.app/) is an open-source cross-platform AI client that synchronizes across Windows, macOS, Linux, iOS, Android, and Web with a focus on "minimalism, cross-platform, and local-first." It natively supports custom service providers of the "OpenAI API" type, allowing direct access to Ace Data Cloud without additional plugins. **One API Token can access over 60 large models including Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc.** This article describes the configuration process. ## Application Process To integrate Ace Data Cloud in ChatBox, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Download ChatBox Visit the [ChatBox official website](https://chatboxai.app/) to download by platform, or use the portable [Web version](https://web.chatboxai.app/) directly: - Desktop: Windows `.exe`, macOS `.dmg` (distinguishing Intel / Apple Silicon), Linux AppImage - Mobile: App Store, Google Play, direct link for Android on the official website ## Configure Ace Data Cloud Launch ChatBox and go to **Settings → Model**, select **OpenAI API** for "Model Provider" (do not select Azure or Custom), then fill in: | Field | Value | Description | | ----------- | ------------------------------- | ------------------------------------------------ | | API Key | Your Ace Data Cloud Token | Token copied from the console | | API Host | `https://api.acedata.cloud` | Only fill in the root domain, **do not include `/openai` or `/v1`** | | API Path | `/v1/chat/completions` | ChatBox defaults to `/chat/completions`, must be manually changed to this | The request path for ChatBox is `{API Host} + {API Path}`, so only the root domain should be filled in: | API Host | Final Request | Result | | ------------------------------------- | --------------------------------------------------------- | -------------------------- | | `https://api.acedata.cloud` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (`/openai` does not have `/v1`) | | `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/v1/chat/completions` | 404 | ChatBox will not automatically call `/v1/models`, you need to manually enter the model ID in the "Custom Model" input box at the bottom of the model settings page (one per line), and save it to select from the model dropdown in the chat interface. ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Note | | --------- | ------------------------------------------- | ----------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Reasoning, vision, long context | For a complete list of models, please refer to the [Ace Data Cloud service documentation](https://platform.acedata.cloud/documents). ## Verification of Integration If you are unsure whether the issue lies with ChatBox or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Frequently Asked Questions ### Prompt 404 Not Found This is usually due to the API Host having added `/openai` or `/v1`. The Host should only be `https://api.acedata.cloud`, and the path should default to `/v1/chat/completions`. ### Prompt 401 / token_mismatched Please confirm that the "API Key" pasted is the Ace Data Cloud Token (without the `Bearer ` prefix and no extra spaces), and that the balance of the associated application is sufficient. ### Cannot see models in the dropdown ChatBox will not automatically pull the model list; you must manually enter the model ID in the "Custom Model" box and save it. ### Want to generate images in ChatBox Ace Data Cloud's image generation is a separate Images API (`/openai/images/generations`), with a different path from the chat interface, and the image entry in ChatBox cannot be directly connected. For drawing, please refer to the [Image Generation API documentation](https://platform.acedata.cloud/documents/openai-images-generations) for curl / SDK calls. ## Learn More - [ChatBox Official Website](https://chatboxai.app/) ｜ [ChatBox GitHub](https://github.com/chatboxai/chatbox) - [Official Guide for Integrating OpenAI Compatible Services (BYOK)](https://chatboxai.app/en/guide/byok/openai) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Image Generation API Documentation](https://platform.acedata.cloud/documents/openai-images-generations) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in Cherry Studio [Cherry Studio](https://cherry-ai.com/) is an open-source multi-model AI desktop client that supports Windows, macOS, and Linux. Its ability to "customize service providers + custom API addresses" allows you to integrate any OpenAI-compatible gateway (including Ace Data Cloud) into the same client. With Ace Data Cloud, you only need one API Token to use in Cherry Studio: - **Dialogue Models**: Claude, GPT (including `gpt-4o-image` and other conversational image generation models), Gemini, Grok, Kimi, GLM, DeepSeek. - **Dedicated Image Models**: Directly call `gpt-image-2`, `gpt-image-1.5`, `nano-banana-pro`, etc., via command line / SDK (this part of Cherry Studio's UI cannot be directly accessed for now; the native calling method is provided at the end of this document). This document strictly follows the UI fields described in the [Cherry Studio official documentation](https://docs.cherry-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang) to explain how to integrate Ace Data Cloud into Cherry Studio. ## Application Process To integrate Ace Data Cloud into Cherry Studio, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Key Background To correctly configure Cherry Studio, you need to understand two things—both come from the Cherry Studio official documentation and the actual interface structure of Ace Data Cloud. ### 1. Cherry Studio's "API Address" Concatenation Rules Cherry Studio has clear stipulations for the **API Address** field among OpenAI-type providers (source: [Cherry Studio Official Documentation — Model Service Settings](https://docs.cherry-ai.com/pre-basic/settings/providers)): - **Does not end with `#`**: Cherry Studio will automatically append `/v1/chat/completions` at the end. For example, if you enter `https://api.example.com`, the actual request will be `https://api.example.com/v1/chat/completions`. - **Ends with `#`**: Cherry Studio uses the part before `#` as the complete URL directly, **without any further concatenation**. This is key for pointing to non-default paths (e.g., `/openai/chat/completions`, `/gemini/chat/completions`). ### 2. One Entry Point per Model Family in Ace Data Cloud Ace Data Cloud provides independent OpenAI-compatible entry points for each upstream model family (e.g., GPT uses `/openai`, Gemini uses `/gemini`). Additionally, `/v1/chat/completions` is a **universal entry point** that can route any family’s model ID (not limited to Claude). Below is a list of each family’s entry points for easier group management. | Model Family | Ace Data Cloud Interface | Some Available Models | | ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Claude | `https://api.acedata.cloud/v1/chat/completions` | `claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001` | | GPT (OpenAI) | `https://api.acedata.cloud/openai/chat/completions` | `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4`, `gpt-5.2`, `gpt-5-mini`, `gpt-4o`, `gpt-4o-image`, `o3` | | Gemini | `https://api.acedata.cloud/gemini/chat/completions` | `gemini-3.1-pro`, `gemini-3.0-pro`, `gemini-3.5-flash`, `gemini-2.5-pro` | | Grok | `https://api.acedata.cloud/grok/chat/completions` | `grok-4`, `grok-3` | | Kimi | `https://api.acedata.cloud/kimi/chat/completions` | `kimi-k3`, `kimi-k2.6`, `kimi-k2.5` | | GLM | `https://api.acedata.cloud/glm/chat/completions` | `glm-5.1`, `glm-4.7`, `glm-4.6` | | DeepSeek | `https://api.acedata.cloud/deepseek/chat/completions` | `deepseek-r1`, `deepseek-v3`, `deepseek-v4-flash` | > The entry for Claude happens to be the default path of Cherry Studio `/v1/chat/completions`, so **Claude does not need to add `#`**; other families must use the complete URL with `#`. For a complete model list, please refer to the API documentation of each service in the [Ace Data Cloud Console](https://platform.acedata.cloud/documents). Therefore, in Cherry Studio, you can **create a separate provider configuration for each model family**; if you find it cumbersome, you can also create just one pointing to `/v1/chat/completions` (without adding `#` at the end) and add the model IDs of each family—this universal entry point is valid for all families. ## General Steps: Adding a Custom Provider in Cherry Studio Below is the general process for adding a custom provider in Cherry Studio; all families will follow this step, just with different "API Address" and model IDs. 1. Click on **Settings** (gear icon) in the left navigation bar of Cherry Studio, and select the **Model Services** tab. 2. Click the **`+ Add`** button below the existing provider list to open the **"Add Provider"** pop-up. 3. Fill in the pop-up: - **Provider Name**: An easily recognizable name, such as `Ace Data Cloud - Claude`. - **Provider Type**: Select **OpenAI** from the dropdown (Cherry Studio custom providers support four types: OpenAI / Gemini / Anthropic / Azure OpenAI). 4. Click "Add" to save. 5. Find the newly added item in the provider list and enter the details page: - **Enable Switch** (top right / right side of the list): Must be turned on; otherwise, the model will not appear in the dialogue selector. - **API Key**: Paste the Ace Data Cloud API Token; you can click the **Check** button next to it to validate the key. - **API Address**: Fill in the corresponding family URL provided in this document (all except Claude should end with `#`). - **Model Management**: Click the **`+ Add`** button to manually enter the model IDs you want to use (must match the IDs given in this document or Ace Data Cloud documentation exactly in case sensitivity). Below is an example for each family. ## Configure Claude - **Provider Type**: `OpenAI` - **API Key**: Ace Data Cloud Token - **API Address**: ```text https://api.acedata.cloud ``` > Do not add `#`. Cherry Studio will automatically append `/v1/chat/completions`, which is the entry point for the Claude service in Ace Data Cloud. - **Added Model IDs (Example)**: `claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001` For the complete model list, please refer to the [Claude AI Service Documentation](https://platform.acedata.cloud/documents/claude). ## Configure GPT / Gemini / Grok / Kimi / GLM / DeepSeek The "API Address" for non-Claude family must end with `#`. For example, for GPT: - **Provider Type**: `OpenAI` - **API Key**: Same as above - **API Address**: ```text https://api.acedata.cloud/openai/chat/completions# ``` - **Added Model IDs (Example)**: `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.4`, `gpt-5.2`, `gpt-5-mini`, `gpt-4o`, `gpt-4o-image`, `o3` The same applies to other families, just replace the API address with: - Gemini: `https://api.acedata.cloud/gemini/chat/completions#` - Grok: `https://api.acedata.cloud/grok/chat/completions#` - Kimi: `https://api.acedata.cloud/kimi/chat/completions#` - GLM: `https://api.acedata.cloud/glm/chat/completions#` - DeepSeek: `https://api.acedata.cloud/deepseek/chat/completions#` Each vendor configuration only needs to add the corresponding family model ID. The same API Token can be reused across all vendors, and the quota is shared. ## Generate Images in Cherry Studio's Conversation: Use `gpt-4o-image` Cherry Studio's "Drawing" panel currently only supports the drawing models of the four built-in providers [DMXAPI, TokenFlux, AiHubMix, Silicon-based Flow](https://docs.cherry-ai.com/cherry-studio/preview/drawing), **custom drawing service providers cannot be added**. At the same time, its OpenAI custom provider sends requests in chat-completion format, which cannot interface with Ace Data Cloud's `/openai/images/generations` Images-API format interface. However, Ace Data Cloud's **`gpt-4o-image`** is a chat-completion format image model—it accepts standard `messages[]` input and returns the generated image in `![](URL)` Markdown format within `choices[0].message.content`, so it can be used directly through Cherry Studio's conversation panel. Configuration method: 1. Reuse the **"Configure GPT (OpenAI)"** provider (API address `https://api.acedata.cloud/openai/chat/completions#`). 2. Under that provider, "+ Add" model `gpt-4o-image`. 3. Create a new conversation, switch to `gpt-4o-image` in the model selector, and directly input the prompt. Cherry Studio will render the image URL in the response as Markdown. If you want the model to modify "an existing image," you can attach the image in the dialog box (Cherry Studio will send it in `image_url` format, consistent with OpenAI's multimodal messages). If there is no image upload button in the dialog box, please enable the "Visual" capability switch for `gpt-4o-image` in "Model Management"—Cherry Studio will only display the image upload entry when the model is marked as having visual capabilities. For complete request/response examples, please refer to the [OpenAI Chat Completion API Documentation's "GPT-4o Drawing Model" section](https://platform.acedata.cloud/documents/openai-chat-completions-integration). ## Advanced: Directly Call Dedicated Image Models like `gpt-image-2` / `nano-banana-pro` `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, `dall-e-3`, `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana` are dedicated Images-API format models, with the request body being `{model, prompt, size, ...}` instead of `{model, messages: [...]}`. They can only be called through Ace Data Cloud's `/openai/images/generations` interface, **and cannot be configured in Cherry Studio**—they can only be directly interfaced using curl / SDK / backend services. Interface address: ```text https://api.acedata.cloud/openai/images/generations ``` Available `model` (completely consistent with Ace Data Cloud OpenAI image service's `model` enumeration): `gpt-image-2`, `gpt-image-1.5`, `gpt-image-1`, `dall-e-3`, `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `nano-banana`. `size` field constraints (from OpenAI image generation interface's official description): can be any `WIDTHxHEIGHT` string, but must meet the conditions that both width and height are multiples of 16, long side ≤ 3840, total pixels ≤ 8,294,400. The preset values given in the documentation are as follows: | Ratio | 1K | 2K | 4K | | ---- | ----------- | ----------- | ----------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | Notes: - **Billing is fixed per image, regardless of `size`.** - The `gpt-image-1` / `gpt-image-1.5` / `gpt-image-2`, `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` family **does not support `n > 1`**: even if a larger `n` is passed, it will only return 1 image and only charge for 1 image. If multiple candidates are needed, please send multiple requests concurrently. - Long-running tasks can pass `callback_url` in the request body, which Ace Data Cloud will use to notify after the image is generated, avoiding occupying the client's waiting connection. ### curl Example Generate a 1:1 1K image with `gpt-image-2`: ```bash curl https://api.acedata.cloud/openai/images/generations \ -H "Authorization: Bearer {token}" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-image-2", "prompt": "A vintage travel poster of the Amalfi Coast, art-deco style, bold typography reads AMALFI", "size": "1024x1024" }' ``` The `data[0].url` in the response is the generated image address. For a complete field description (including parameters such as `image` / `mask` for image editing `/openai/images/edits`), please refer to: - [OpenAI Images Generations API Documentation](https://platform.acedata.cloud/documents/openai-images-generations) - [OpenAI Images Edits API Documentation](https://platform.acedata.cloud/documents/openai-images-edits) ## Why Use Ace Data Cloud in Cherry Studio ### One Token Access to Multiple Dialogue Models Although Cherry Studio natively supports many service providers, each requires separate registration, key application, and individual billing. With Ace Data Cloud, you only need one API Token to use models like Claude, GPT, Gemini, Grok, Kimi, GLM, DeepSeek, and the conversational drawing model `gpt-4o-image` under the same quota. ### Unified Quota and Billing Details All requests are billed based on actual tokens / number of images, and can be viewed uniformly in the [Ace Data Cloud Console - Usage History](https://platform.acedata.cloud/console/usages); the remaining quota can be viewed in real-time in the [Application List](https://platform.acedata.cloud/console/applications). New users receive a free quota upon their first application. ### Direct Connection Available in China Ace Data Cloud provides access nodes within the country, allowing access to models like OpenAI / Anthropic / Gemini in mainland China without the need to build a proxy. ## Restrictions and Notes - **Each model family requires independent vendor configuration**: Claude uses default concatenation, while other families must include `#` and point to their respective paths. Sending `gpt-5.5` to `/v1/chat/completions` will not be recognized. - **The trailing `#` cannot be omitted**: For all vendors pointing to `/openai/...`, `/gemini/...`, `/grok/...`, `/kimi/...`, `/glm/...`, `/deepseek/...`, the API address must end with `#`, otherwise Cherry Studio will forcibly append `/v1/chat/completions`. - **Be sure to enable the switch after saving**: Cherry Studio's official documentation clearly reminds, "After successful configuration, be sure to turn on the switch in the upper right corner, otherwise the service provider will remain disabled." - **Cherry Studio cannot directly connect to dedicated Images API models**: `gpt-image-2` / `nano-banana-pro` / `dall-e-3` can only be called directly via curl / SDK at `/openai/images/generations`. To draw in Cherry Studio, please use the chat-completion form of `gpt-4o-image`. - **`n > 1` is not supported**: The `gpt-image-*`, `nano-banana*` family only returns 1 image per request. ## Frequently Asked Questions ### Prompt `token_mismatched` or `invalid_token` Please confirm that the API Token pasted in the "API Key" field is the Ace Data Cloud API Token, and that the Token is still available in the [Console](https://platform.acedata.cloud/console/applications) and the application's balance is sufficient. ### Prompt model does not exist / `api_not_implemented` / 404 In most cases, this is due to sending the model to the wrong entry point (for example, sending `gpt-5.5` to the Claude entry), or the API address of a non-Claude vendor missing the trailing `#`. Please create vendors for each family separately according to the comparison table in the "Key Background" section of this article. ### The model has been added, but cannot be seen in the dialogue selector Please check if the "enable switch" in the upper right corner of the target vendor is turned on. Cherry Studio will not add its models to the dialogue selector if the vendor is not enabled. ### Want to use `gpt-image-2` in Cherry Studio The "Drawing" panel in Cherry Studio and the OpenAI custom vendor currently cannot connect to Ace Data Cloud's `/openai/images/generations`. Please use `gpt-4o-image` (conversational drawing, can be used directly in Cherry Studio dialogue), or call the dedicated Images API directly using curl / SDK outside of Cherry Studio. ### How to check remaining quota Log in to the [Ace Data Cloud Console](https://platform.acedata.cloud/console) to view the current account's remaining quota and usage history. ## Learn More - [Cherry Studio Official Website](https://cherry-ai.com/) ｜ [Custom Service Provider Documentation](https://docs.cherry-ai.com/pre-basic/providers/zi-ding-yi-fu-wu-shang) ｜ [Model Service Settings Documentation](https://docs.cherry-ai.com/pre-basic/settings/providers) - [Ace Data Cloud Claude AI Service](https://platform.acedata.cloud/documents/claude) - [Ace Data Cloud OpenAI Chat Completion API (including `gpt-4o-image` drawing example)](https://platform.acedata.cloud/documents/openai-chat-completions-integration) - [Ace Data Cloud OpenAI Images Generations API](https://platform.acedata.cloud/documents/openai-images-generations) - [Ace Data Cloud OpenAI Images Edits API](https://platform.acedata.cloud/documents/openai-images-edits) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in Jan [Jan](https://jan.ai/) is an open-source AI desktop client that emphasizes "offline-first + privacy protection." It comes with a local inference engine (based on llama.cpp, available on Apple Silicon with MLX) that can run open-source models directly on the local machine; at the same time, it supports any OpenAI-compatible endpoints through the **Remote Engine** mechanism. With this capability, you can connect to Ace Data Cloud, allowing local models to coexist with cloud-based models like Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, and over 60 others within the same client, **using just one API Token**. This article describes the configuration process. ## Application Process To connect Ace Data Cloud in Jan, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will automatically return to the current page. You will receive a free quota upon your first application, allowing you to experience Ace Data Cloud's model services for free. ## Download Jan Go to the [Jan official website](https://jan.ai/) to download according to your platform (Windows, macOS, Linux). For Apple Silicon models, please download the arm64 package for optimal performance. ## Configure Ace Data Cloud Jan categorizes models into **Local Engine** (running locally) and **Remote Engine** (third-party API). Ace Data Cloud connects via the OpenAI-compatible protocol as a Remote Engine. Open Jan, go to **Settings → Model Providers**, find the **OpenAI** card and edit it: | Field | Value | Description | | --------- | ---------------------------------- | ---------------------------- | | API Key | Your Ace Data Cloud Token | Token copied from the console | | Base URL | `https://api.acedata.cloud/v1` | **Must end with `/v1`, do not include a trailing slash** | > The requirement for the Base URL to end with `/v1` is a clear stipulation in Jan's official documentation. If you do not want to overwrite the original OpenAI configuration, you can create a new `openai-compatible` type provider by clicking "+ Add Provider" and filling in the same content. Jan does not automatically pull the model list from Ace Data Cloud; you need to click **+ Add Model** at the bottom of the same editing page to fill in the model IDs one by one. After adding, the models will appear in the dropdown in the upper left corner, marked with a "Cloud" icon to distinguish between remote and local. ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Notes | | --------- | -------------------------------------------- | -------------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Inference, vision, long context | For a complete list of models, please refer to the [Ace Data Cloud service documentation](https://platform.acedata.cloud/documents). ## Verification If you are unsure whether the issue lies with Jan or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: Local + Cloud Hybrid Jan has a built-in local OpenAI-compatible API Server that can be enabled (Settings → Local API Server). Once enabled, it listens on `http://localhost:1337/v1/chat/completions`, running the local models you downloaded. This allows you to point the Base URL to local for free debugging in frameworks like LangChain / LlamaIndex, while switching to Ace Data Cloud remote models for complex tasks. The conversation context will not be lost when switching models. ## Frequently Asked Questions ### Prompt Connection error or 404 This is usually due to the Base URL missing `/v1`. Change it to `https://api.acedata.cloud/v1` (it must end with `/v1`, and should not be written as `.../openai/v1`). ### Prompt 401 Unauthorized Please confirm that the API Key pasted is the Ace Data Cloud Token (without the `Bearer ` prefix and no extra spaces), and that the balance of the associated application is sufficient. ### Remote models not appearing in the dropdown Jan does not automatically call `/v1/models`; you must manually **+ Add Model** to add the model IDs. ### Can I upload images for the model to analyze? Yes, but you need to choose models that support vision, such as `gpt-5`, `gemini-3.1-pro`, `claude-opus-4-8`. ## Learn More - [Jan Official Website](https://jan.ai/) ｜ [Jan GitHub](https://github.com/menloresearch/jan) ｜ [Jan Documentation](https://jan.ai/docs) - [Jan Official Documentation for Connecting Custom OpenAI-Compatible Endpoints](https://jan.ai/docs/desktop/remote-models/custom-endpoint) - [Jan Official Documentation for Local API Server](https://jan.ai/docs/desktop/api-server) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in LibreChat [LibreChat](https://www.librechat.ai/) is a highly configurable open-source AI client that replicates the complete experience of ChatGPT in one interface, with support for multiple providers and enterprise-level configurations. It features a `librechat.yaml` configuration file that describes all providers, models, and routing rules, which can be versioned and code-reviewed. It natively supports custom OpenAI-compatible endpoints, allowing integration with Ace Data Cloud, **where a single API Token can access over 60 large models including Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc.** This article outlines the configuration process. ## Application Process To integrate Ace Data Cloud into LibreChat, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Deploying LibreChat LibreChat is deployed via Docker Compose. First, prepare the directory and download the official configuration: ```bash mkdir -p ~/librechat && cd ~/librechat curl -O https://raw.githubusercontent.com/danny-avila/LibreChat/main/docker-compose.yml curl -O https://raw.githubusercontent.com/danny-avila/LibreChat/main/.env.example mv .env.example .env ``` In the `.env` file, generate `JWT_SECRET`, `JWT_REFRESH_SECRET`, `CREDS_KEY`, `CREDS_IV`, and other security keys using `openssl rand -hex 32`, and set `ALLOW_REGISTRATION` as needed. ## Configuring Ace Data Cloud Create `librechat.yaml` and set Ace Data Cloud as a custom OpenAI-compatible endpoint (for complete field descriptions, see the official [Custom Endpoints documentation](https://www.librechat.ai/docs/quick_start/custom_endpoints), replacing `{token}` with your Token): ```yaml version: 1.0.5 cache: true endpoints: custom: - name: "Ace Data Cloud" apiKey: "{token}" baseURL: "https://api.acedata.cloud/v1" models: default: - "gpt-5" - "gpt-5-mini" - "gpt-4o" - "claude-opus-4-8" - "claude-sonnet-4-6" - "gemini-3.1-pro" - "gemini-3-flash-preview" - "grok-4" - "deepseek-v3" - "kimi-k3" fetch: false # false=use fixed list; true=automatically GET /v1/models titleConvo: true titleModel: "gpt-5-mini" modelDisplayLabel: "Ace Data Cloud" ``` In the `docker-compose.yml` file, mount this file into the container under the `api` service, then start with `docker compose up -d`: ```yaml volumes: - type: bind source: ./librechat.yaml target: /app/librechat.yaml ``` Note the path rules for `baseURL`: | baseURL | Actual Request | Result | | ------------------------------------- | ------------------------------------------------------ | -------------------------- | | `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | Also available | | `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (`/openai` does not have `/v1`) | | `https://api.acedata.cloud` | `https://api.acedata.cloud/chat/completions` | 404 (missing `/v1`) | ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Notes | | --------- | ------------------------------------------- | ------------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Reasoning, vision, long context | For a complete list of models, please refer to the [Ace Data Cloud service documentation](https://platform.acedata.cloud/documents). ## Verification of Integration If you are unsure whether the issue lies with LibreChat or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: YAML Configuration Tips `librechat.yaml` supports multiple endpoint groups (e.g., "flagship group" and "economy group"), allowing you to use `apiKey: "user_provided"` so that each user can enter their own Key, with usage calculated separately; `titleModel: "gpt-5-mini"` can automatically generate conversation titles using a cheaper model; `dropParams` can be used to uniformly remove unsupported parameters from an upstream to avoid 400 errors. For more details, see [librechat.yaml configuration details](https://www.librechat.ai/docs/configuration/librechat_yaml). ## Frequently Asked Questions ### Cannot see Ace Data Cloud endpoint after starting This is usually due to the yaml not being mounted into the container or indentation errors. Check the volumes in `docker-compose.yml` and verify the yaml indentation. ### Getting a 404 error The `baseURL` may have been written as `.../openai/v1` or missing `/v1`. Change it to `https://api.acedata.cloud/v1`. ### Model dropdown is empty If `fetch: true` but `/v1/models` fails, change it to `fetch: false` and manually list `default`. ### Changes to yaml do not take effect You need to restart the container: `docker compose restart api`. ## Learn More - [LibreChat Official Website](https://www.librechat.ai/) ｜ [LibreChat GitHub](https://github.com/danny-avila/LibreChat) ｜ [librechat.yaml Configuration Details](https://www.librechat.ai/docs/configuration/librechat_yaml) - [LibreChat Custom Endpoints Official Documentation](https://www.librechat.ai/docs/quick_start/custom_endpoints) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in LobeChat [LobeChat](https://lobehub.com/) is an open-source AI client that features "modern UI + plugin ecosystem + knowledge base + one-click self-deployment." You can use the official online version (PWA) or run a private version on your own server using Docker. It natively supports custom OpenAI-compatible endpoints, allowing access to Ace Data Cloud, **with one API Token accessing over 60 large models including Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc.** This article describes the configuration process. ## Application Process To integrate Ace Data Cloud into LobeChat, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Configuring Ace Data Cloud Go to LobeChat's **Application Settings → Language Model**, find the **OpenAI** card and enable it, then fill in: | Field | Value | Description | | -------------- | ---------------------------------- | ------------------------------- | | API Key | Your Ace Data Cloud Token | Token copied from the console | | API Proxy URL | `https://api.acedata.cloud/v1` | **Must end with `/v1`** | | Client Request Mode | Enabled | Direct browser connection, Key does not go through LobeChat server | LobeChat will not automatically append `/v1` to the Base URL, the request path is directly `{API Proxy URL}/chat/completions`: | API Proxy URL | Actual Request | Result | | ------------------------------------------- | ------------------------------------------------------- | -------------------------- | | `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | Also usable | | `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (`/openai` does not have `/v1`) | | `https://api.acedata.cloud` | `https://api.acedata.cloud/chat/completions` | 404 (missing `/v1`) | LobeChat will automatically call `/v1/models` to fetch models, and if Ace Data Cloud returns many models, the interface will be lengthy. It is recommended to manually fill in an allow list in "Model List → Custom Model Name," separated by commas. If you need to customize the display name, you can use `=`, for example, `gpt-5=GPT-5 Flagship Version`. ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Notes | | ---------- | ------------------------------------------ | -------------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Reasoning, vision, long context | For the complete model list, please refer to the [Ace Data Cloud Service Documentation](https://platform.acedata.cloud/documents). ## Verification of Integration If you are unsure whether the issue lies with LobeChat or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: Docker Self-Deployment If you want to deploy a private version for team use, you can start it with a single Docker command (replace `{token}` with your Token): ```bash docker run -d \ --name lobe-chat \ -p 3210:3210 \ -e OPENAI_API_KEY={token} \ -e OPENAI_PROXY_URL=https://api.acedata.cloud/v1 \ -e ACCESS_CODE=your-secret-password \ -e OPENAI_MODEL_LIST="gpt-5,claude-opus-4-8,gemini-3.1-pro,grok-4,deepseek-v3" \ lobehub/lobe-chat:latest ``` Open `http://your-server-IP:3210`, enter `ACCESS_CODE` to use it, and team members do not need to fill in their own Keys. For a complete explanation of the environment variables used above, such as `OPENAI_API_KEY`, `OPENAI_PROXY_URL`, `OPENAI_MODEL_LIST`, see the [LobeChat Model Service Provider Environment Variable Documentation](https://lobehub.com/docs/self-hosting/environment-variables/model-provider). If using nginx for reverse proxy with HTTPS, be sure to add `proxy_buffering off;`, otherwise, streaming responses will be buffered. For more deployment forms, please refer to [LobeChat Self-Deployment Guide](https://lobehub.com/docs/self-hosting/start) and [Docker Compose Deployment](https://lobehub.com/docs/self-hosting/platform/docker-compose). ## Frequently Asked Questions ### Prompt 404 Not Found This is usually due to the API proxy URL being written as `.../openai/v1` or missing `/v1`. Change it to `https://api.acedata.cloud/v1`. ### Model List is Empty Turn on the "Client Request Mode" switch; or manually fill in the model allow list in "Custom Model Name." ### Prompt 401 Unauthorized Please confirm that the API Key pasted is the Ace Data Cloud Token (without the `Bearer ` prefix and no extra spaces), and that the balance of the associated application is sufficient. ## Learn More - [LobeChat Official Website](https://lobehub.com/) ｜ [LobeChat GitHub](https://github.com/lobehub/lobe-chat) ｜ [Self-Hosting Documentation](https://lobehub.com/docs/self-hosting/start) - [LobeChat Configuration OpenAI Provider Official Documentation](https://lobehub.com/docs/usage/providers/openai) - [LobeChat Model Provider Environment Variables Documentation](https://lobehub.com/docs/self-hosting/environment-variables/model-provider) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in NextChat [NextChat](https://github.com/ChatGPTNextWeb/NextChat) (formerly ChatGPT-Next-Web) is a well-known open-source AI client in the Chinese community, featuring "one-click deployment + cross-platform + PWA," allowing you to quickly deploy your own AI website on Vercel / Cloudflare / Docker. It natively supports custom OpenAI-compatible endpoints, enabling access to Ace Data Cloud, **with one API Token accessing over 60 large models including Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc.** This article describes the configuration process. ## Application Process To integrate Ace Data Cloud into NextChat, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. You will receive a free quota upon your first application, allowing you to experience Ace Data Cloud's model services for free. ## Download NextChat You can use the desktop version (download `.exe` / `.dmg` / AppImage from the [Releases page](https://github.com/ChatGPTNextWeb/NextChat/releases)), the [Web online version](https://app.nextchat.club/), or deploy it yourself on Vercel / Cloudflare / Docker (see the advanced section below). ## Configure Ace Data Cloud Start NextChat and go to **Settings → Model Services**: | Field | Value | Description | | -------------- | ------------------------------- | ---------------------------------------- | | Model Provider | `OpenAI` | Use OpenAI compatible protocol | | OpenAI API URL | `https://api.acedata.cloud` | Only fill in the root domain, **do not include `/openai` or `/v1`** | | API Key | Your Ace Data Cloud Token | Token copied from the console | NextChat will automatically append `/v1/chat/completions` to the API URL, so only the root domain needs to be filled in: | API URL | Actual Request | Result | | ------------------------------------------ | ----------------------------------------------------------- | ---------------------------- | | `https://api.acedata.cloud` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404 (no `/v1` under `/openai`) | | `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/v1/chat/completions` | 404 | In the "Custom Model Names" box, fill in the models separated by English commas. NextChat supports special syntax: `+model_name` to add, `-model_name` to hide, `model_name=display_name` to customize the display name, `-all` to hide all first. The cleanest writing is recommended: ```text -all,+gpt-5=GPT-5,+claude-opus-4-8=Claude Opus 4.8,+gemini-3.1-pro=Gemini 3.1 Pro,+grok-4=Grok 4,+deepseek-v3=DeepSeek V3 ``` ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Notes | | ---------- | -------------------------------------------- | -------------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Reasoning, vision, long context | For a complete list of models, please refer to the [Ace Data Cloud service documentation](https://platform.acedata.cloud/documents). ## Verification of Integration If you are unsure whether the issue lies with NextChat or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: One-Click Deployment to Your Own Domain NextChat supports deploying your own AI website. For example, using Docker (replace `{token}` with your Token): ```bash docker run -d \ --name nextchat \ -p 3000:3000 \ -e OPENAI_API_KEY={token} \ -e BASE_URL=https://api.acedata.cloud \ -e CODE=your-password \ -e CUSTOM_MODELS="-all,+gpt-5,+claude-opus-4-8,+gemini-3.1-pro,+grok-4,+deepseek-v3" \ yidadaa/chatgpt-next-web ``` When deploying on Vercel / Cloudflare, configure the same `OPENAI_API_KEY`, `BASE_URL`, `CODE`, and `CUSTOM_MODELS` in the project's environment variables. The `CODE` supports multiple access passwords separated by commas for usage statistics. For a complete explanation of the above environment variables (the default `BASE_URL` is `https://api.openai.com`, and the `+/-/=/-all/+all` syntax for `CUSTOM_MODELS`), please refer to the [NextChat official README](https://github.com/ChatGPTNextWeb/NextChat#environment-variables). ## Frequently Asked Questions ### Prompt 404 Not Found This usually occurs when the API URL is written as `.../openai` or `.../openai/v1`. Change it to `https://api.acedata.cloud` so that NextChat can append `/v1/chat/completions` itself. ### Models not added in the dropdown Check the format of `CUSTOM_MODELS`, each model must be preceded by `+`; if `-all` is used, ensure that the required models are added back with `+`. ### Prompt 401 Unauthorized Please confirm that the API Key pasted is the Ace Data Cloud Token (without the `Bearer ` prefix and no extra spaces), and that the balance of the associated application is sufficient. ## Learn More - [NextChat GitHub](https://github.com/ChatGPTNextWeb/NextChat) ｜ [NextChat Online Version](https://app.nextchat.club/) - [NextChat Environment Variable Official Documentation (README)](https://github.com/ChatGPTNextWeb/NextChat#environment-variables) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Using Ace Data Cloud in Open WebUI [Open WebUI](https://openwebui.com/) (formerly Ollama WebUI) is an open-source AI client designed for team/enterprise scenarios, natively supporting multi-user and RBAC, knowledge base and RAG, model parallel comparison, and Pipelines extension, and can be fully privately deployed. It natively supports custom OpenAI-compatible endpoints, allowing access to Ace Data Cloud, **with one API Token accessing over 60 large models including Claude, GPT, Gemini, Grok, DeepSeek, Kimi, GLM, etc.** This article describes the configuration process. ## Application Process To access Ace Data Cloud in Open WebUI, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page. There is a free quota available for first-time applicants, allowing you to experience Ace Data Cloud's model services for free. ## Deploying and Configuring Ace Data Cloud Open WebUI connects to OpenAI-compatible endpoints through environment variables, and can be deployed with a single Docker command (replace `{token}` with your Token): ```bash docker run -d \ --name open-webui \ -p 3000:8080 \ -e WEBUI_SECRET_KEY=$(openssl rand -base64 32) \ -e OPENAI_API_BASE_URL=https://api.acedata.cloud/v1 \ -e OPENAI_API_KEY={token} \ -v open-webui:/app/backend/data \ ghcr.io/open-webui/open-webui:main ``` | Environment Variable | Function | | ----------------------------------- | ------------------------------------- | | `OPENAI_API_BASE_URL` | Ace Data Cloud entry, **must end with `/v1`** | | `OPENAI_API_KEY` | Your Token | | `WEBUI_SECRET_KEY` | Session encryption key, automatically generated | | `-v open-webui:/app/backend/data` | Persistent conversation/user data | Open `http://your-server-IP:3000`, and the first registered account will automatically become the administrator. Note the path rules for the Base URL: | OPENAI_API_BASE_URL | Actual Request | Result | | ------------------------------------ | ---------------------------------------------------- | ------------------------ | | `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | Correct | | `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | Also available | | `https://api.acedata.cloud/openai/v1`| `https://api.acedata.cloud/openai/v1/chat/completions`| 404 (`/openai` does not have `/v1`) | After logging in, go to **Admin Panel → Settings → Connections** and click "Verify Connection" to validate; in **Settings → Models**, you can filter and pin commonly used models. > In addition to using environment variables, Open WebUI also supports adding connections directly in the interface: go to **Admin Settings → Connections**, click ➕ and fill in the URL (`https://api.acedata.cloud/v1`) and API Key, and Open WebUI will automatically call `/models` to fetch the model list. For more details, see the official documentation [Starting With OpenAI-Compatible Servers](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible). ## Recommended Models The following model IDs have been verified as available through Ace Data Cloud `GET /v1/models` and `POST /v1/chat/completions`: | Family | Model ID | Notes | | -------- | ----------------------------------------- | ----------------------- | | GPT | `gpt-5`, `gpt-5-mini`, `gpt-4o` | OpenAI flagship / cost-effective / classic multimodal | | Claude | `claude-opus-4-8`, `claude-sonnet-4-6` | Anthropic flagship / balanced | | Gemini | `gemini-3.1-pro`, `gemini-3-flash-preview` | Google multimodal / fast | | Grok | `grok-4` | xAI, natively connected | | DeepSeek | `deepseek-v3` | High cost-performance, Chinese-friendly | | Kimi | `kimi-k3` | Reasoning, vision, ultra-long context | Open WebUI will automatically call `/v1/models` to fetch all models by default. For a complete list of models, please refer to the [Ace Data Cloud service documentation](https://platform.acedata.cloud/documents). ## Verification of Integration If you are unsure whether the issue lies with Open WebUI or the network, you can first verify the endpoint directly using curl (replace `{token}` with your Token): ```bash curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'Authorization: Bearer {token}' \ -H 'Content-Type: application/json' \ -d '{ "model": "gpt-5", "messages": [{"role": "user", "content": "ping"}] }' ``` If you receive an OpenAI-compatible `chat.completion` object, it indicates that both the Token and endpoint are ready; if you receive `HTTP 403 used_up`, it means the Token is valid but the balance is insufficient, and you can recharge at the [console](https://platform.acedata.cloud/console/applications). ## Advanced: Knowledge Base and Multi-User Open WebUI's knowledge base (RAG) uses ChromaDB by default to store vectors, and the embedding model can be specified as `text-embedding-3-large` (via Ace Data Cloud). The original document only exists on your server, and only the matched segments will be sent to the model. In **Admin Panel → Users**, you can manage user roles (Pending / User / Admin); it is recommended to set the "Default User Role" to `pending`, requiring new users to be reviewed before they can use it, to prevent unauthorized registrations from consuming quotas. If using nginx as a reverse proxy, please add `proxy_buffering off;` and `client_max_body_size 100M;`. ## Frequently Asked Questions ### Prompt Connection error / 404 This is usually because `OPENAI_API_BASE_URL` is written as `.../openai/v1` or is missing `/v1`. Change it to `https://api.acedata.cloud/v1`. ### Unable to chat after uploading documents In the RAG settings of the Admin Panel, set the embedding model to `text-embedding-3-large` (OpenAI provider). ### Data loss after container restart You need to mount the data volume `-v open-webui:/app/backend/data` at startup. ## Learn More - [Open WebUI Official Website](https://openwebui.com/) ｜ [Open WebUI GitHub](https://github.com/open-webui/open-webui) ｜ [Quick Start Documentation](https://docs.openwebui.com/getting-started/quick-start) - [Official Documentation for Integrating OpenAI-Compatible Endpoints in Open WebUI](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible) - [Ace Data Cloud OpenAI Chat Completions API Documentation](https://platform.acedata.cloud/documents/openai-chat-completions) - [Ace Data Cloud Service List](https://platform.acedata.cloud/documents) - [Ace Data Cloud Console](https://platform.acedata.cloud/console) --- # Telegram Account Proxy User Guide The Telegram account proxy provides an independent, persistent MCP and REST interface for your personal Telegram account. Each instance serves only one account, and the login session is stored in the instance's independent persistent volume. > This is a personal account authorization service, not the Telegram Bot API. Only connect accounts that you personally own and have explicitly authorized; do not use it for spam messages, bulk cold sending, or bypassing Telegram restrictions. ## Login 1. Create a Telegram account proxy instance in the console. 2. Once the instance is ready, click "Generate Login QR Code." 3. Open **Settings → Devices → Link Desktop Device** in the Telegram client and scan the QR code. 4. If the account has two-step verification enabled, enter the Telegram two-step verification password in the console. The password is submitted directly to your tenant instance and will not be saved in the platform configuration. After a successful login, the instance will reuse the persistent login state after a restart or upgrade. Logging out will revoke the Telegram session for that instance. ## MCP Access The console will display the exclusive MCP address and Bearer access token: ```json { "mcpServers": { "telegram": { "url": "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Please protect the Bearer token as you would your account password. All login, REST, and MCP interfaces must carry this token, except for `/health`. ## REST Example View the currently authorized account: ```bash curl https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \ -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" ``` List recent sessions: ```bash curl "https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/chats?limit=20" \ -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" ``` Send a message: ```bash curl -X POST https://telegram-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \ -H "Authorization: Bearer $PROXY_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"target":"me","text":"Hello from my Telegram proxy"}' ``` `target` can be a session ID, username, or exact session name. Production automation should control the sending frequency and perform explicit confirmation before sending to third parties. --- # Claude Chat Completion API Application and Usage Anthropic Claude is a very powerful AI dialogue system that can generate smooth and natural replies in just a few seconds by inputting prompts. Claude stands out in the industry with its excellent language understanding and generation capabilities, and today, Claude has been widely applied across various industries and fields, with its influence becoming increasingly significant. Whether for daily conversations, creative writing, or professional consulting and coding, Claude can provide astonishing intelligent assistance, greatly enhancing human work efficiency and creativity. This document mainly introduces the usage process of the Claude Chat Completion API, allowing us to easily utilize the official Claude dialogue features. ## Application Process To use the Claude Chat Completion API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform, without needing to apply separately for each service.** The first application will grant a free quota for a free experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Claude Chat Completion API →](https://platform.acedata.cloud/documents/claude-chat-completions) ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, we need to fill in at least three pieces of content: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the model category we choose to use from the Claude official website; here we mainly have 20 types of models, and details can be found in the models we provide. The last parameter is `messages`, which is an array of our input questions; it is an array that allows multiple questions to be uploaded simultaneously, with each question containing `role` and `content`, where `role` indicates the role of the questioner, and we provide three identities: `user`, `assistant`, and `system`. The other `content` is the specific content of our question. You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing. Common optional parameters: - `max_tokens`: Limits the maximum number of tokens for a single reply. - `temperature`: Generates randomness, between 0-2, with larger values being more divergent. - `n`: How many candidate replies to generate at once. - `response_format`: Sets the return format.

After the call, we find the return result as follows: ```json { "id": "msg_bdrk_01Q6WN27v95ypCa1kbanAQ6K", "model": "claude-opus-4-8", "object": "chat.completion", "created": 1768619365, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` The return result contains multiple fields, described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the selected Claude official model. - `choices`, the response information provided by Claude for the question. - `usage`: Statistics on token usage for this Q&A. In the Chat Completions format, `usage.prompt_tokens` already includes the input tokens from cache hits. Billing will apply cache read and write prices to the corresponding parts based on `prompt_tokens_details.cached_tokens` and `cached_creation_tokens`, without double counting cached tokens as regular input. Among them, `choices` contains Claude's response information, and the `choices` inside it shows the specific information of Claude's answer, as can be seen in the figure.

It can be seen that the `content` field in `choices` contains the specific content of Claude's reply. ## Streaming Response This interface also supports streaming responses, which is very useful for web integration, allowing the webpage to achieve a word-by-word display effect. If you want to return responses in a streaming manner, you can change the `stream` parameter in the request header to `true`. Modify as shown in the figure, but the calling code needs to have corresponding changes to support streaming responses.

After changing `stream` to `true`, the API will return the corresponding JSON data line by line, and we need to make corresponding modifications at the code level to obtain the line-by-line results. Python sample calling code: ```python import requests url = "https://api.acedata.cloud/v1/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "claude-opus-4-20250514", "messages": [{"role":"user","content":"Hello"}], "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The output effect is as follows: ```json data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": ""}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": "Hello!"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " How can I help you"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {"content": " today?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null} data: {"id": "msg_bdrk_01LPPqDjLKMgfSwTRMRty9VT", "object": "chat.completion.chunk", "created": 1768619445, "model": "claude-opus-4-20250514", "system_fingerprint": null, "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 12, "total_tokens": 20, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}} data: [DONE] ``` It can be seen that there are many `data` in the response, and the `choices` in `data` are the latest response content, consistent with the content introduced above. The `choices` are the newly added response content, which you can use to connect to your system. At the same time, the end of the streaming response is determined based on the content of `data`. If the content is `[DONE]`, it indicates that the streaming response has completely ended. The returned `data` result has multiple fields, described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the Claude model selected from the official website. - `choices`, the response information provided by Claude for the question. JavaScript is also supported, for example, the streaming call code for Node.js is as follows: ```javascript const options = { method: "post", headers: { accept: "application/json", authorization: "Bearer {token}", "content-type": "application/json", }, body: JSON.stringify({ model: "claude-opus-4-20250514", messages: [{ role: "user", content: "Hello" }], stream: true, }), }; fetch("https://api.acedata.cloud/v1/chat/completions", options) .then((response) => response.json()) .then((response) => console.log(response)) .catch((err) => console.error(err)); ``` Java sample code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "claude-opus-4-20250514"); jsonObject.put("messages", [{"role":"user","content":"Hello"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/v1/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Other languages can be rewritten accordingly; the principle is the same. ## Multi-turn Dialogue If you want to integrate multi-turn dialogue functionality, you need to upload multiple question words in the `messages` field. The specific examples of multiple question words are shown in the image below:

Python sample call code: ```python import requests url = "https://api.acedata.cloud/v1/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "claude-opus-4-20250514", "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello! How can I help you today?"},{"role":"user","content":"What I say just now?"}] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple question words, you can easily achieve multi-turn dialogue and receive the following response: ```json { "id": "msg_bdrk_01Y1wfQmd89g968TVbFu57Yc", "model": "claude-opus-4-20250514", "object": "chat.completion", "created": 1768619674, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "You said \"Hello\" - that was your first message to me in our conversation." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 29, "completion_tokens": 20, "total_tokens": 49, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` It can be seen that the information contained in `choices` is consistent with the basic usage content, which includes the specific content of Claude's responses to multiple dialogues, allowing for answers to corresponding questions based on multiple dialogue contents. ## Deep Thinking Model The claude-opus-4-20250514-thinking and claude-sonnet-4-20250514-thinking models are different from other models in that they can perform deep thinking based on the question words to provide answers, and return the results of the thinking process to you. This article will demonstrate the deep thinking functionality through a specific example. Next, you can fill in the corresponding content on the Claude Chat Completion API interface, as shown in the figure:

At the same time, you can notice that there is corresponding code generation on the right side, which you can copy to run directly, or you can click the "Try" button for testing.

After the call, we find that the returned result is as follows: ```json { "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH", "object": "chat.completion", "created": 1755444014, "model": "claude-sonnet-4-20250514-thinking", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The sine of 30 degrees is **1/2** or **0.5**.\n\nThis is one of the fundamental trigonometric values. In a 30-60-90 triangle, the sides are in the ratio 1:√3:2, where the side opposite to the 30° angle has length 1 and the hypotenuse has length 2, giving us sin(30°) = 1/2.", "reasoning_content": "The user is asking for the sine of 30 degrees. This is a basic trigonometry question.\n\nThe sine of 30 degrees is a well-known value. In a 30-60-90 triangle, the sides are in the ratio 1:√3:2. \n\nFor a 30° angle:\n- The opposite side is 1\n- The hypotenuse is 2\n- So sin(30°) = opposite/hypotenuse = 1/2 = 0.5\n\nThis is one of the standard trigonometric values that's commonly memorized." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 60, "completion_tokens": 239, "total_tokens": 299, "prompt_tokens_details": { "cached_tokens_details": {} }, "completion_tokens_details": {} } } ``` It can be seen that the response information in `choices` is obtained after deep thinking, and it also provides relevant reasoning process content, where `reasoning_content` in `content` indicates the model's thinking process. The response information in `choices` needs to be rendered using `markdown` syntax to achieve the best experience, which also reflects the powerful advantages of our model's networking capabilities. ## Visual Model The claude-sonnet-4-20250514 is a multimodal large language model developed by Claude, which adds visual understanding capabilities based on claude-4. This model can process both text and image inputs simultaneously, achieving cross-modal understanding and generation. The text processing using the claude-sonnet-4-20250514 model is consistent with the basic usage content mentioned above. Below is a brief introduction on how to use the model's image processing capabilities. The image processing capability of the claude-sonnet-4-20250514 model is mainly achieved by adding a `type` field to the original `content`, which indicates whether the uploaded content is text or an image, thus utilizing the image processing capabilities of the claude-sonnet-4-20250514 model. The following mainly discusses how to call this functionality using Curl and Python. - Curl Script Method ``` curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What'\''s in this image?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/ueugot.png" } } ] } ] }' ``` - Python Script Method ```python import requests url = "https://api.acedata.cloud/v1/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "claude-sonnet-4-20250514", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What's in this image?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/ueugot.png" } }, ], } ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Then you can obtain the following result, where the field information in the result is consistent with the above: ```json { "id": "msg_bdrk_01NCrxpZmV17bhQJJRQEFEb9", "model": "claude-sonnet-4-20250514", "object": "chat.completion", "created": 1768628904, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "This image shows an API request configuration interface for what appears to be an AI chat completion service. Here are the key elements:\n\n**Request Body Parameters:**\n\n1. **model** (required string) - Set to \"claude-opus-4-202505...\" - specifies which AI model to use\n\n2. **messages** (required array) - Contains the conversation history with:\n - **role** (required string) - Set to \"user\" \n - **content** (required string) - Contains \"Hello\" as the message content\n\n3. **stream** (boolean) - Set to \"true\" - enables partial message deltas like in ChatGPT\n\n4. **max_tokens** (number) - Field for setting maximum tokens that can be generated in the response\n\n5. **n** (number) - Specifies how many chat completion choices to generate for each input\n\nThe interface has a dark theme with white text on black/dark gray backgrounds. There's a \"Fill Example\" button at the bottom right and various dropdown menus and input fields for configuring the API request parameters. A red trash/delete icon is visible, likely for removing message entries." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1570, "completion_tokens": 252, "total_tokens": 1822, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` The content of the response can be seen as based on images, so the text and image processing capabilities of the claude-3-7-sonnet-20250219 model can be easily utilized through the above two methods. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to easily implement the conversational features of the official Claude using the Claude Chat Completion API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Gemini Chat Completion API Application and Usage Google Gemini is a very powerful AI conversation system that can generate smooth and natural replies in just a few seconds by inputting prompts. Gemini provides amazing intelligent assistance, greatly enhancing human work efficiency and creativity. This document mainly describes the usage process of the Gemini Chat Completion API, allowing us to easily utilize the official Gemini conversation features. ## Application Process To use Gemini Chat Completion API, first open the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) and copy your API Token. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in, you will be redirected to sign in and brought back to this page automatically. **A single API Token works across every service on the platform — no need to subscribe per service.** New accounts receive free starter credit; when it runs low you can top up your shared balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Full documentation: [Gemini Chat Completion API →](https://platform.acedata.cloud/documents/gemini-chat-completions) ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, we need to fill in at least three pieces of information: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the category of the Gemini official model we choose to use. Here we mainly have 6 types of models; details can be found in the models we provide. The last parameter is `messages`, which is an array of the questions we input. It is an array that allows multiple questions to be uploaded simultaneously, with each question containing `role` and `content`. The `role` indicates the role of the questioner, and we provide three identities: `user`, `assistant`, and `system`. The other `content` is the specific content of our question. You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing.

After the call, we find that the returned result is as follows: ```json { "id": "chatcmpl-20251122212413908150493uPhjTUO9", "model": "gemini-2.5-pro", "object": "chat.completion", "created": 1763817866, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "I am a large language model, trained by Google.", "reasoning_content": "**My Reasoning: Answering the User's Question**\n\nOkay, here's how I'm going to approach answering the user's question, \"What model are you?\". The core is to be direct and informative. First, I have to be clear about my origin. Then, I need to make sure the explanation is accessible, given that the user may not be familiar with technical jargon. I need to explain what a \"large language model\" actually *does*, and provide relatable examples. I know the user might be looking for a specific name, like other models have, so I'll address that directly and then wrap it up with an invitation to continue.\n\nSo, here's my plan:\n\n1. **Lead with the key info:** I'll begin by stating that I am a large language model created by Google. That is the fundamental, most critical piece of the puzzle.\n2. **Define the buzzword:** Then, I'll explain that \"large language model\" in simple terms. I'll explain what I *do* - process and generate text; how I *do* it - by training on huge amounts of text data; and the *goal* - to be able to communicate like a human.\n3. **Provide context:** After that, to make the concept even clearer, I'll provide a list of examples of my capabilities. I'll mention things like answering questions, summarizing texts, writing stories, translating languages, and brainstorming ideas.\n4. **Acknowledge the lack of a personal name:** I'll anticipate the likely question about a model name (like ChatGPT) by clearly stating that I don't have a personal name and that it's best to think of me as an AI assistant from Google.\n5. **End with an invitation:** Lastly, I'll end with a simple, friendly question to invite further interaction and to guide the conversation.\n\nWith this approach, I am confident I can successfully answer this important question.\n" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 8, "completion_tokens": 932, "total_tokens": 940, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 921 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` The returned result contains multiple fields, described as follows: - `id`, the ID generated for this conversation task, used to uniquely identify this conversation task. - `model`, the selected Gemini official model. - `choices`, the response information provided by Gemini for the question. - `usage`: statistics on the tokens for this Q&A. Among them, `choices` contains the response information from Gemini, and the `choices` inside it shows the specific information of Gemini's response, as can be seen in the figure.

It can be seen that the `content` field in `choices` contains the specific content of Gemini's reply. ## Streaming Response This interface also supports streaming responses, which is very useful for web integration, allowing the webpage to display results word by word. If you want to return responses in a streaming manner, you can change the `stream` parameter in the request header to `true`. Modify as shown in the figure, but the calling code needs to have corresponding changes to support streaming responses.

After changing `stream` to `true`, the API will return the corresponding JSON data line by line, and we need to make corresponding modifications at the code level to obtain line-by-line results. Python sample calling code: ```python import requests url = "https://api.acedata.cloud/gemini/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gemini-2.5-pro", "messages": [{"role":"user","content":"Hello,What model are you?"}], "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The output effect is as follows: ```json data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Define My Nature**\n\nMy thinking has started. The user wants to know my nature, asking a direct \"what are you?\" The initial step was straightforward: identifying the query. Now, I recall my fundamental identity: I'm a large language model. This is the core truth I aim to convey.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Refining My Response**\n\nI've added the crucial information that I'm trained by Google to the basic \"large language model\" identity. My next step is considering what being a \"large language model\" actually entails, so I can explain my core capabilities. I'm focusing on providing context without going into specific technical details or model names. I want to convey my function in a way the user can easily understand.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Confirming Core Identity**\n\nI'm now solidifying my response. The user's query about my model affiliation needs a focused answer. I've pinpointed that \"trained by Google\" is essential, providing key context. I'm resisting the urge to mention any specific model names, as it's not relevant. The aim is to deliver a direct, accurate statement. My goal remains a clear and concise reply, avoiding technical jargon and getting straight to the relevant point.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "I am a large language model, trained by Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null} data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}} data: [DONE] ``` It can be seen that there are many `data` in the response, and the `choices` in `data` are the latest response content, consistent with the content introduced above. The `choices` are the newly added response content, which you can integrate into your system based on the results. The end of the streaming response is determined by the content of `data`; if the content is `[DONE]`, it indicates that the streaming response has completely ended. The returned `data` result has multiple fields, described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the selected Gemini official model. - `choices`, the response information provided by Gemini for the query. JavaScript is also supported, for example, the streaming call code for Node.js is as follows: ```javascript const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "gemini-2.5-pro", "messages": [{"role":"user","content":"Hello,What model are you?"}], "stream": true }) }; fetch("https://api.acedata.cloud/gemini/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` Java sample code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "gemini-2.5-pro"); jsonObject.put("messages", [{"role":"user","content":"Hello,What model are you?"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/gemini/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Other languages can be rewritten accordingly; the principle is the same. ## Multi-turn Dialogue If you want to integrate multi-turn dialogue functionality, you need to upload multiple queries in the `messages` field. The specific examples of multiple queries are shown in the image below:

Python sample call code: ```python import requests url = "https://api.acedata.cloud/gemini/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gemini-2.5-pro", "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello there! How can I help you today?"},{"role":"user","content":"What model are you?"}] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple queries, you can easily achieve multi-turn dialogue and obtain responses as follows: ```json { "id": "chatcmpl-20251122214426669120974AKFwnJd1", "model": "gemini-2.5-pro", "object": "chat.completion", "created": 1763819072, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "I am a large language model, trained by Google.", "reasoning_content": "Okay, here's how I'd approach this, thinking as a sophisticated AI:\n\nFirst, the user is directly querying my core identity: \"What model are you?\" That's a simple, straightforward question. My primary task is to provide accurate and helpful information, so I need to answer this immediately.\n\nRight off the bat, I know the answer. I *am* a large language model. That's my fundamental architecture and operational principle. I'm built on a vast network of connections and trained on a massive dataset.\n\nThen I must add the necessary context. Crucially, I have to provide the source of my training. I *was* trained by Google. That's a key identifier. It provides the user with valuable information about my origin and potential biases (though I'm trained to mitigate them).\n\nNow I must construct the response. My goal is to be factual, concise, and understandable.\n\nThe synthesized response is something like: \"I am a large language model, trained by Google.\"\n\nI have to assess the output: Does it meet the criteria? It's clear. It states what I am, it includes a critical piece of information on my origins, and it avoids jargon. No misleading promises.\n\nFinal verification: Does it actually answer the question? Yes. Is the information correct and truthful? Yes. Is it concise? Absolutely. Is the tone appropriate for any user? Yes. And, finally, this is the standard, approved response. Excellent.\n" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 16, "completion_tokens": 265, "total_tokens": 281, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 16, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 254 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` It can be seen that the information contained in `choices` is consistent with the basic usage content, which includes the specific content of responses from Gemini to multiple dialogues, allowing for answers to corresponding questions based on multiple dialogue contents. ## Gemini-3.0 Multimodal Model Request example: ```json { "model": "gemini-3.0-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is the content of the image?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/qzx2z1.png" } } ] } ], "stream": false } ``` Example result: ```json { "id": "chatcmpl-20251206001815715692730UVZe38kB", "model": "gemini-3.0-pro", "object": "chat.completion", "created": 1764951548, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "This is a half-length outdoor portrait photo of a young woman.\n\nHere is the main content description of the image:\n\n* **Appearance**: The girl in the photo has long, straight black hair, delicate features, and fair skin. She has a gentle smile and is looking at the camera.\n* **Outfit**: She is wearing a cream or light apricot puff-sleeve top, paired with black clothing (which looks like a suspender skirt or vest).\n* **Lighting Atmosphere**: Sunlight is shining from the left rear, casting a warm golden halo on her hair, creating a fresh and beautiful atmosphere.\n* **Background**: The background is blurred, indicating that it is outdoors, with an empty road (asphalt) and green trees along the roadside.\n\nOverall, this photo gives a sweet, sunny, and neighborly girl feeling." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1092, "completion_tokens": 1271, "total_tokens": 2363, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 4, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 1072 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` Of course, you can also submit a video link, with the specific input as follows: ```json { "model": "gemini-3.0-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is the content of the video?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/58yioe.mp4" } } ] } ], "stream": false } ``` Example result: ```json { "id": "chatcmpl-20251206002711949677736JC9yL8AE", "model": "gemini-3.0-pro", "object": "chat.completion", "created": 1764952060, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The content of this video is full of fun, mainly showcasing a **ginger cat** confidently jogging along a country road at dusk.\n\nSpecific details are as follows:\n\n1. **Visual Content**:\n * The main character is an orange tabby cat.\n * The background is during sunset (or sunrise), with soft golden light. There are wooden fences and open fields by the roadside, and a silhouette of a pedestrian in the distance.\n * The camera uses a low-angle shot, sometimes capturing the cat running towards the camera, sometimes capturing its departing figure, along with close-ups of the cat's face and patterns.\n\n2. **Sound Characteristics (Key Points)**:\n * The voiceover of the video is very distinctive. Although the visuals show a light-footed cat running, the accompanying sound is **heavy and rhythmic hoofbeats** (or sounds similar to clogs/high heels striking the ground).\n * This contrast in sound and visuals creates a sense of humor, as if this cat considers itself a galloping steed.\n\nOverall, this is a pet video that uses the contrast of sound and visuals to create cute and humorous moments." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 915, "completion_tokens": 1423, "total_tokens": 2338, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 5, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 1162 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0 } } ``` It can be seen from the above that the Gemini 3.0 model supports multimodal understanding. ## Gemini-3.1 Multimodal Model Gemini 3.1 Pro is an upgraded version of Gemini 3.0 Pro, with the underlying model being `gemini-3.1-pro-preview`, also supporting multimodal inputs such as text, images, and videos, with stronger reasoning and understanding capabilities. The usage is completely consistent with Gemini 3.0 Pro; just replace the `model` parameter with `gemini-3.1-pro`. Request example: ```json { "model": "gemini-3.1-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is the content of the image?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/qzx2z1.png" } } ] } ], "stream": false } ``` Gemini 3.1 Pro also supports video understanding: ```json { "model": "gemini-3.1-pro", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "What is the content of the video?" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/58yioe.mp4" } } ] } ], "stream": false } ``` The return format is consistent with Gemini 3.0 Pro, as detailed in the description of the Gemini-3.0 multimodal model section above. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to easily implement the official Gemini chat functionality using the Gemini Chat Completion API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # GLM Chat Completion API Application and Usage GLM (General Language Model) is a new generation of large language model series launched by Zhipu AI (智谱 AI / Z.ai), which possesses strong understanding and generation capabilities in both Chinese and English. It performs excellently in tasks such as Chinese scenarios, code generation, reasoning, and multi-turn dialogue. The new generation models like GLM-5.1, GLM-4.7, and GLM-4.6 have made significant optimizations in long context, tool invocation, and code tasks, and can be widely applied in scenarios such as intelligent Q&A, content creation, code assistance, and customer service robots. This document mainly introduces the usage process of the GLM Chat Completion API. With it, you can easily call the GLM series models through a unified OpenAI compatible interface. When using `glm-5.2` in Coze (扣子), please refer to the [Coze Custom Model Tutorial](https://platform.acedata.cloud/documents/coze-integration) and select the OpenAI Chat Completions protocol. ## Application Process To use the GLM Chat Completion API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in. After completing this, you will be automatically returned to the current page. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a free experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [GLM Chat Completion API →](https://platform.acedata.cloud/documents/glm-chat-completions) ## Basic Usage The request address for the GLM Chat Completion API is `https://api.acedata.cloud/glm/chat/completions`, using Bearer Token for authentication, and the request body is compatible with the OpenAI Chat Completions protocol. When using this interface for the first time, we need to fill in at least three contents: - `authorization`: Select Bearer Token directly from the dropdown list. - `model`: Choose the GLM model to call, currently supported models include: - `glm-5.2`: The latest flagship model, suitable for complex reasoning, code, and Agent tasks. - `glm-5.1`: The previous generation flagship model, strong overall capability. - `glm-4.7`: Excellent performance in reasoning, tool invocation, and code tasks. - `glm-4.6`: General dialogue model, balancing effect and cost. - `glm-3-turbo`: Classic dialogue model, suitable for general text generation tasks. - `messages`: An array of prompts, each message contains `role` and `content`, where `role` supports three roles: `user`, `assistant`, `system`. Common optional parameters: - `max_tokens`: Limits the maximum number of tokens in a single reply. - `temperature`: Randomness of generation, between 0-2, the larger the value, the more divergent. - `top_p`: Nucleus sampling parameter, controlling the cumulative probability threshold of candidate tokens. - `n`: How many candidate replies to generate at once. - `stream`: Whether to enable streaming response, default is `false`. - `stop`: Custom stop sequence. Here is the simplest Python call example: ```python import requests url = "https://api.acedata.cloud/glm/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "glm-5.2", "messages": [ {"role": "user", "content": "hello"} ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we find the returned result as follows: ```json { "id": "msg_202604262252030313862701a04e33", "model": "glm-5.2", "object": "chat.completion", "created": 1777215124, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! 👋 How can I assist you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 10, "completion_tokens": 23, "total_tokens": 33 } } ``` The main fields of the returned result are explained as follows: - `id`: The unique ID of this dialogue task. - `created`: The creation time of this dialogue task (Unix timestamp, in seconds). - `model`: The name of the GLM model actually called. - `choices`: The list of replies generated by the model. `choices[i].message.content` is the specific text of the model's reply, and `finish_reason` indicates the reason for ending (`stop`, `length`, `tool_calls`, `content_filter`, etc.). - `usage`: Token usage statistics for this request, including `prompt_tokens`, `completion_tokens`, and `total_tokens`. ## Streaming Response This interface supports streaming responses (Server-Sent Events), which is very useful for web integration, allowing the webpage to achieve a word-by-word display effect. If you want to return responses in a streaming manner, set the `stream` parameter in the request body to `true`. Python sample call code: ```python import requests url = "https://api.acedata.cloud/glm/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "glm-4.7", "messages": [{"role": "user", "content": "hi"}], "stream": True } response = requests.post(url, json=payload, headers=headers, stream=True) for line in response.iter_lines(): if line: print(line.decode("utf-8")) ``` The output effect is as follows (excerpt): ```text data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "", "role": "assistant"}, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "Hello! How can I"}, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "help you"}, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {"content": "?"}, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [{"delta": {}, "finish_reason": "stop", "index": 0}], "usage": null} data: {"id": "msg_2026042622521271f765bbc3734ce1", "object": "chat.completion.chunk", "created": 1777215133, "model": "glm-4.7", "choices": [], "usage": {"prompt_tokens": 1420, "completion_tokens": 18, "total_tokens": 1438}} data: [DONE] ``` You can see that there are many `data` in the response, each containing an incremental fragment. `choices[i].delta.content` is the newly added text fragment for the current chunk, and you can concatenate these fragments to form a complete reply. When the content of `data` is `[DONE]`, it indicates the end of the streaming response. The last chunk with `usage` will summarize the token usage for this request. JavaScript (Node.js) example: ```javascript const options = { method: "POST", headers: { accept: "application/json", authorization: "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ model: "glm-4.7", messages: [{ role: "user", content: "hi" }], stream: true }) }; const response = await fetch("https://api.acedata.cloud/glm/chat/completions", options); const reader = response.body.getReader(); const decoder = new TextDecoder("utf-8"); while (true) { const { value, done } = await reader.read(); if (done) break; process.stdout.write(decoder.decode(value)); } ``` Java example code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "glm-4.7"); jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "hi"))); jsonObject.put("stream", true); MediaType mediaType = MediaType.parse("application/json; charset=utf-8"); RequestBody body = RequestBody.create(jsonObject.toString(), mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/glm/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); ``` Other languages can be rewritten similarly; the principle is the same. ## Multi-turn Dialogue If you want to implement multi-turn dialogue functionality, you need to sequentially place the historical dialogues into the `messages` array, maintaining the alternating order of `user` and `assistant`. Python example call code: ```python import requests url = "https://api.acedata.cloud/glm/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "glm-4.7", "messages": [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi! How can I assist you today?"}, {"role": "user", "content": "What did I say just now?"} ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple questions, you can easily achieve multi-turn dialogue and receive responses like the following: ```json { "id": "msg_20260426225208b95324e9945a48d3", "model": "glm-4.7", "object": "chat.completion", "created": 1777215128, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "You said: **\"Hello\"** 😊\n\nLet me know if you need anything else!" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 48, "completion_tokens": 37, "total_tokens": 85 } } ``` As you can see, the information contained in `choices` is consistent with basic usage, and the model provides replies based on the complete dialogue history, thus supporting multi-turn contextual interaction. ## System Prompt You can add a message with a `role` of `system` at the beginning of `messages` to constrain the model's role, style, or behavior: ```python payload = { "model": "glm-4.7", "messages": [ {"role": "system", "content": "You are a senior Chinese writing assistant, please respond in a concise and professional tone."}, {"role": "user", "content": "Please introduce the GLM model in three sentences."} ] } ``` ## Function Calling The GLM model supports OpenAI-compatible Function Calling, and you can declare callable functions through the `tools` parameter. The model will return structured function call information in `choices[i].message.tool_calls` when needed. ```python payload = { "model": "glm-4.7", "messages": [ {"role": "user", "content": "What is the weather like in Beijing today?"} ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "Query the weather for a specified city", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "City name"} }, "required": ["city"] } } } ] } ``` If the model decides to call a tool, the `finish_reason` in the returned result will change to `tool_calls`, and the function name and parameters in JSON string form will be provided in `message.tool_calls`. You can execute that function and return the result as a message with `role` of `tool` back to the model, thus completing the full tool calling loop. ## Model Selection Recommendations ``` | Model | Applicable Scenarios | | -------------- | ------------------------------------- | | `glm-5.2` | Latest flagship, recommended for complex reasoning, coding, and Agent tasks | | `glm-5.1` | Previous generation flagship, suitable for complex reasoning and long document analysis | | `glm-4.7` | Tool invocation, code generation, Agent orchestration, and other tasks | | `glm-4.6` | Balanced choice for general conversation and content creation | | `glm-3-turbo` | General text generation tasks, cost-sensitive scenarios | ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Missing or invalid request parameters. - `400 api_not_implemented`: Unsupported parameters or models used. - `401 invalid_token`: Unauthorized, Bearer Token is missing or invalid. - `429 too_many_requests`: Rate limit triggered, please try again later. - `500 api_error`: Internal server error or upstream temporarily unavailable. ### Error Response Example ```json { "trace_id": "69ea9bcf-c5da-41a3-be97-c80912a08523", "error": { "code": "api_error", "message": "Service is temporarily unavailable, please retry later." } } ``` When `api_error` is returned and the message is `Service is temporarily unavailable, please retry later.`, it usually indicates that the upstream GLM service is temporarily unavailable. It is recommended to retry with exponential backoff or switch to another available GLM model (for example, temporarily switch from `glm-5.1` to `glm-4.7` or `glm-4.6`). ## Conclusion Through this document, you have learned how to use the GLM Chat Completion API to call Zhipu AI's GLM series models, including basic calls, streaming responses, multi-turn conversations, system prompts, and tool invocations. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Grok Chat Completion API Application and Usage xAI Grok is a very powerful AI dialogue system that can generate smooth and natural replies in just a few seconds by inputting prompts. Grok stands out in the industry with its unique humorous style and real-time web information retrieval capabilities. Today, Grok has emerged in multiple innovative fields, and its influence is rapidly expanding. Whether for daily conversations, creative writing, or technical analysis and code debugging, Grok can provide insightful intelligent assistance, bringing a new dimension of support to users' decision-making and creation. This document mainly introduces the usage process of the Grok Chat Completion API, allowing us to easily utilize the official Grok dialogue features. ## Application Process To use Grok Chat Completion API, first open the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) and copy your API Token. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in, you will be redirected to sign in and brought back to this page automatically. **A single API Token works across every service on the platform — no need to subscribe per service.** New accounts receive free starter credit; when it runs low you can top up your shared balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Full documentation: [Grok Chat Completion API →](https://platform.acedata.cloud/documents/grok-chat-completions) ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, we need to fill in at least three pieces of content: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the category of the Grok official model we choose to use. Here we mainly have 8 types of models; details can be found in the models we provide. The last parameter is `messages`, which is an array of our input questions. It is an array that allows multiple questions to be uploaded simultaneously, with each question containing `role` and `content`. The `role` indicates the role of the questioner, and we provide three identities: `user`, `assistant`, and `system`. The other `content` is the specific content of our question. You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing. Common optional parameters: - `max_tokens`: Limits the maximum number of tokens for a single reply. - `temperature`: Generates randomness, between 0-2, with larger values being more divergent. - `n`: How many candidate replies to generate at once.

After the call, we find the returned result as follows: ```json { "id": "foaicmpl-13936918-cb99-49e1-b94c-bde98b482ed4", "model": "grok-3", "object": "chat.completion", "created": 1755839683, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Yo! What's up? 😎 Ready to dive into whatever you're pondering about today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 8, "completion_tokens": 20, "total_tokens": 28, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null } } ``` The returned result contains multiple fields, described as follows: - `id`: The ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`: The selected Grok official model. - `choices`: The response information provided by Grok for the question. - `usage`: Statistical information regarding the tokens for this Q&A. Among them, `choices` contains the response information from Grok, and the `choices` inside it shows the specific information of Grok's response, as can be seen in the figure.

It can be seen that the `content` field inside `choices` contains the specific content of Grok's reply. ## Streaming Response This interface also supports streaming responses, which is very useful for web integration, allowing the webpage to achieve a word-by-word display effect. If you want to return responses in a streaming manner, you can change the `stream` parameter in the request header to `true`. Modify as shown in the figure, but the calling code needs to have corresponding changes to support streaming responses.

After changing `stream` to `true`, the API will return the corresponding JSON data line by line, and we need to make corresponding modifications at the code level to obtain the line-by-line results. Python sample calling code: ```python import requests url = "https://api.acedata.cloud/grok/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "grok-3", "messages": [{"role":"user","content":"Hello"}], "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The output effect is as follows: ```json data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "Yo, "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "what"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'s g"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ood?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": " Rea"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "dy t"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "o di"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ve i"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "nto "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "what"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ever"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": " you"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'re "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "pond"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "erin"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "g ab"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "out "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "toda"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "y?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}} data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 18, "total_tokens": 26, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}} data: [DONE] ``` You can see that there are many `data` in the response, and the `choices` in `data` is the latest response content, consistent with the content introduced above. The `choices` is the newly added response content, and you can integrate it into your system based on the results. The end of the streaming response is determined by the content of `data`; if the content is `[DONE]`, it indicates that the streaming response has completely ended. The returned `data` result has multiple fields, described as follows: - `id`, the ID generated for this conversation task, used to uniquely identify this conversation task. - `model `, the selected Grok official model. - `choices`, the response information provided by Grok for the question words. JavaScript is also supported, for example, the streaming call code for Node.js is as follows: ```javascript const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "grok-3", "messages": [{"role":"user","content":"Hello"}], "stream": true }) }; fetch("https://api.acedata.cloud/grok/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` Java sample code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "grok-3"); jsonObject.put("messages", [{"role":"user","content":"Hello"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/grok/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Other languages can be rewritten accordingly; the principle is the same. ## Multi-turn Conversation If you want to integrate multi-turn conversation functionality, you need to upload multiple question words in the `messages` field. The specific example of multiple question words is shown in the image below:

Python sample call code: ```python import requests url = "https://api.acedata.cloud/grok/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "grok-3", "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"What model are you?"},{"role":"user","content":"What did I just say?"}] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple question words, you can easily achieve multi-turn conversation and receive responses like the following: ```json { "id": "foaicmpl-984ebc53-76b3-4d33-b0e8-0307ab4965af", "model": "grok-3", "object": "chat.completion", "created": 1755839996, "choices": [ { "index": 0, "message": { "role": "assistant", "content": "You said, \"Hello.\"" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 27, "completion_tokens": 6, "total_tokens": 33, "prompt_tokens_details": { "cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0 }, "completion_tokens_details": { "text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0 }, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null } } ``` As you can see, the information contained in `choices` is consistent with the basic usage content, which includes the specific content of Grok's responses to multiple conversations, allowing you to answer corresponding questions based on multiple conversation contents. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to easily implement the conversation functionality of the official OpenAI ChatGPT using the OpenAI Chat Completion API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Hailuo Videos Generation API Integration Instructions This article will introduce the integration instructions for the Hailuo Videos Generation API, which can generate official Hailuo videos by inputting custom parameters. ## Application Process To use the Hailuo Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page, inviting you to register and log in. After completing this, you will be automatically returned to the current page. **One API Token can call all services on the platform, without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Hailuo Videos Generation API →](https://platform.acedata.cloud/documents/hailuo-videos-integration) ## Basic Usage First, understand the basic usage, which involves inputting the prompt `prompt`, the action `action`, the first frame reference image `first_image_url`, and the model `model` to obtain the processed result. You first need to simply pass a field `action` with the value `generate`, and then we also need to input the model, which currently mainly includes the image-to-video model `minimax-i2v` and the text-to-video model `minimax-t2v`. The specific content is as follows:

Here we can see that we have set the Request Headers, including: - `accept`: the format of the response result you want to receive, filled in as `application/json`, which means JSON format. - `authorization`: the key to call the API, which can be directly selected after application. Additionally, we set the Request Body, including: - `model`: the model for generating the video, mainly the image-to-video model `minimax-i2v` and the text-to-video model `minimax-t2v`. - `action`: the action for this video generation task. - `first_image_url`: the link to the first frame reference image that must be uploaded when selecting the image-to-video model `minimax-i2v`, Base64 encoding is not supported. - `prompt`: the prompt. - `callback_url`: the URL to receive the callback result. - `async`: optional, when set to `true`, the interface immediately returns `task_id`, and there is no need to provide `callback_url`, then the result can be polled through the corresponding task query interface. After selection, you can find that the corresponding code is also generated on the right side, as shown in the figure:

Click the "Try" button to test, as shown in the above figure, we obtained the following result: ```json { "success": true, "task_id": "baf1034c-684c-46be-ae6d-89ebb89b690d", "trace_id": "3221eb74-1a25-447a-ba69-7d9b310e306c", "data": [ { "id": "0pv8yhe4fdrge0cmckpv23pd2g", "model": "minimax-t2v", "prompt": "Internal heat", "video_url": "https://platform.cdn.acedata.cloud/czjl/qoueLWBokF3ud6tdVD6VJTZuXTnK5HaMO2qAOS46Ef8VSBFUA/tmp9e3u11c1.output.mp4", "state": "succeeded" } ] } ``` The returned result contains multiple fields, described as follows: - `success`: the status of the video generation task at this time. - `task_id`: the ID of the video generation task at this time. - `trace_id`: the tracking ID of the video generation at this time. - `data`: the result list of the video generation task at this time. - `id`: the video ID of the video generation task at this time. - `prompt`: the prompt of the video generation task at this time. - `model`: the cover link of the video generation task at this time. - `video_url`: the video link of the video generation task at this time. - `state`: the status of the video generation task at this time. We can see that we have obtained satisfactory video information, and we only need to access the generated Hailuo video using the video link address in `data`. Additionally, if you want to generate the corresponding integration code, you can directly copy it, for example, the CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/hailuo/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "prompt": "Internal heat" }' ``` ## Asynchronous Callback Since the time taken by the Hailuo Videos Generation API to generate is relatively long, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field, representing the current task ID. When the task is completed, the result of the generated video will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let’s understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, we use a public Webhook sample site https://webhook.site/, where you can open the site to obtain a Webhook URL, as shown in the figure: ![](https://cdn.acedata.cloud/cjjfly.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83`. Next, we can set the field `callback_url` to the above Webhook URL, while filling in the corresponding parameters, as shown in the figure:

Click to run, and you will immediately receive a result, as follows: ``` { "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840" } ``` After a moment, we can observe the result of the generated video at `https://webhook.site/580b81f5-596e-4321-b03f-606770b0bb83`, as shown in the figure: ![](https://cdn.acedata.cloud/7jngb4.png) The content is as follows: ```json { "success": true, "task_id": "05aff65c-5e84-442b-8e29-3a5d27130840", "trace_id": "b9856b8a-725d-45c9-befe-e789d9fd9ffb", "data": [ { "id": "t80jhsf96srg80cmcm6b0rk8gm", "model": "minimax-t2v", "prompt": "Internal heat", "video_url": "https://platform.cdn.acedata.cloud/czjl/YPaUz2DcwpJqItTXAG9XHAoEoj3dbF0XPU69LT5nefCMzBFUA/tmp8s_59jez.output.mp4", "state": "succeeded" } ] } ``` You can see that the result contains a `task_id` field, and the other fields are similar to the above text. This field can be used to associate tasks. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Hailuo Videos Generation API to generate videos by inputting prompt words and a reference image for the first frame. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # HappyHorse Videos API Integration Instructions This document introduces the integration method for the HappyHorse Videos API. This interface supports text-to-video, first-frame image-to-video, reference image-to-video, and video editing through a unified `/happyhorse/videos` endpoint and the `action` parameter. ## Application Process To use the HappyHorse Videos API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, after which you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos) ## Operation Types The `action` determines the generation mode for this request: - `generate`: Text-to-video, default action, supports `happyhorse-1.0-t2v` and `happyhorse-1.1-t2v`, must provide `prompt`. - `image_to_video`: First-frame image-to-video, supports `happyhorse-1.0-i2v` and `happyhorse-1.1-i2v`, must provide `image_url`. - `reference_to_video`: Reference image-to-video, supports `happyhorse-1.0-r2v` and `happyhorse-1.1-r2v`, must provide `prompt` and 1–9 `image_urls`. - `video_edit`: Video editing, supports `happyhorse-1.0-video-edit`, must provide `prompt` and `video_url`, can additionally provide 0–5 reference images `image_urls`. Each action defaults to using the 1.1 model; `video_edit` currently only has `happyhorse-1.0-video-edit`. ## Basic Usage Text-to-video only requires providing `prompt`, and you can also specify parameters like `resolution`, `ratio`, `duration`, etc.: ```json { "action": "generate", "model": "happyhorse-1.1-t2v", "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting", "resolution": "720P", "ratio": "16:9", "duration": 5 } ``` An example of the returned result is as follows: ```json { "success": true, "task_id": "27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1", "trace_id": "6071ab5e-2f37-46f0-9e07-f1e378112e69", "data": [ { "id": "9650580f-6d9e-4bc1-823a-29011790c5cb", "video_url": "https://platform2.cdn.acedata.cloud/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1.mp4", "state": "succeeded", "duration": 5, "resolution": "720P", "ratio": null } ] } ``` Field descriptions: - `success`: Whether this request was successful. - `task_id`: Ace Data Cloud task ID, can be used to query task status. - `trace_id`: Tracking ID for this request, used for troubleshooting. - `data`: List of video results. - `id`: Task ID on the HappyHorse side. - `video_url`: CDN link address of the generated video. - `state`: Task status, can be `pending` / `succeeded` / `error`. - `duration`: Billing video duration, in seconds; for `video_edit`, it is the total duration of input and output videos. - `resolution`: Output resolution. - `ratio`: Output aspect ratio. The corresponding CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/happyhorse/videos' \ -H 'authorization: Bearer ${bearer_token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "happyhorse-1.1-t2v", "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting", "resolution": "720P", "ratio": "16:9", "duration": 5 }' ``` The corresponding Python code is as follows: ```python import requests url = "https://api.acedata.cloud/happyhorse/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json", } payload = { "action": "generate", "model": "happyhorse-1.1-t2v", "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting", "resolution": "720P", "ratio": "16:9", "duration": 5, } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## First-Frame Image-to-Video When using `image_to_video`, the `image_url` will serve as the first frame of the video. The output aspect ratio will try to follow the first frame image, so this action does not require passing `ratio`. ```json { "action": "image_to_video", "model": "happyhorse-1.1-i2v", "image_url": "https://cdn.acedata.cloud/b1c82e4937.png", "prompt": "A cinematic white horse lifts its head, the mane moves gently in the sunrise wind, slow camera push in, warm film lighting", "resolution": "1080P", "duration": 5 } ``` ## Reference Image-to-Video When using `reference_to_video`, you can pass in 1–9 reference images in `image_urls`. You can reference the corresponding images in the prompt using `character1`, `character2`, etc. ```json { "action": "reference_to_video", "model": "happyhorse-1.1-r2v", "prompt": "character1 walks forward through a sunrise meadow with the warm leather and gold trim style from character2", "image_urls": [ "https://cdn.acedata.cloud/b1c82e4937.png", "https://cdn.acedata.cloud/eb75d88a3f.png" ], "resolution": "720P", "ratio": "16:9", "duration": 5 } ``` ## Video Editing When using `video_edit`, you must provide the video URL to be edited `video_url` and the editing intent `prompt`. Optional `image_urls` will serve as reference images, such as for changing outfits, style transfer, or partial replacement. The `audio_setting` can be `auto` or `origin`, where `origin` means to keep the original video audio. ```json { "action": "video_edit", "model": "happyhorse-1.0-video-edit", "prompt": "Apply the warm leather and gold trim style from the reference image while preserving the original camera motion", "video_url": "https://platform2.cdn.acedata.cloud/happyhorse/27837f92-d1c1-4db4-ad9a-4e6e81d9f6c1.mp4", "image_urls": [ "https://cdn.acedata.cloud/eb75d88a3f.png" ], "resolution": "720P", "audio_setting": "auto" } ``` ## Asynchronous Callback Video generation requires a certain processing time. If you do not wish to maintain a long connection while waiting, you can pass in `callback_url`, at which point the API will immediately return `task_id`, and once the task is completed, it will POST the final result to that address: ```json { "action": "generate", "prompt": "A horse running through a snowy forest", "duration": 5, "callback_url": "https://your-domain.com/callback/happyhorse" } ``` The result returned immediately is as follows: ```json { "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea" } ``` If you only wish to poll and do not need a callback, you can also pass in `"async": true`, and then query the task results through the [HappyHorse Tasks API](https://platform.acedata.cloud/documents/happyhorse-tasks). ## Billing Information HappyHorse charges based on the output video duration and resolution: - `720P`: as low as about $0.105 / second. - `1080P`: as low as about $0.18 / second. - `video_edit`: charged based on the total duration of the input and output videos, with the actual billing duration based on the statistics after the task is completed. Failed tasks are not charged and do not count against the free quota. ## Error Handling When there is an issue with the request, the API will return the corresponding error code and description, commonly as follows: - `400`: Request parameters are incorrect, such as action and model not matching, missing `prompt` / `image_url` / `video_url`, or `duration` exceeding the range of 3–15 seconds. - `401`: Authentication failed, token is invalid or does not match the API. - `403`: Insufficient balance, or the prompt hits content review and is rejected. - `429`: Requests are too frequent, triggering rate limiting, please try again later. - `500`: Internal server error or generation failure. --- # Kimi Chat Completion API Application and Usage Kimi is a series of AI models launched by the Dark Side of the Moon. The currently recommended `kimi-k3` is aimed at long-range programming, agents, complex reasoning, and knowledge work, and can be called via the OpenAI-compatible Chat Completions API. This document mainly describes the usage process of the Kimi Chat Completion API, allowing us to easily utilize the official Kimi dialogue features. ## Application Process To use the Kimi Chat Completion API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and will return to the current page automatically after completion. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Kimi Chat Completion API →](https://platform.acedata.cloud/documents/kimi-chat-completions) ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, you need to fill in at least three pieces of content: `authorization` can be selected directly from the dropdown list; `model` is used to select the Kimi model, and it is recommended to use `kimi-k3`; `messages` is an array of dialogue messages, each message contains `role` and `content`, where `role` supports `user`, `assistant`, `system`, and `tool`. You can also notice that there is corresponding code generation on the right side, which you can copy to run directly, or you can click the "Try" button for testing.

Below is a real K3 response obtained using `reasoning_effort: max` (unused extended fields are omitted): ```json { "id": "msg_2D4Btbg1WgvkNE3tCYkR4xGA", "object": "chat.completion", "created": 1784466588, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 86, "completion_tokens": 206, "total_tokens": 292 } } ``` The returned result contains multiple fields, described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the selected Kimi official model. - `choices`, the response information provided by Kimi for the query. - `usage`: statistical information regarding tokens for this Q&A pair. Among them, `choices` contains Kimi's response information, and the `choices` inside it provides the specific information of Kimi's response, as can be seen in the figure.

It can be seen that the `content` field inside `choices` contains the specific content of Kimi's reply; K3 may also return `reasoning_content`, which is used to represent the reasoning process. ## K3 Reasoning Intensity `kimi-k3` always enables reasoning. The top-level request body supports the `reasoning_effort` field, and the currently supported value is `max`; omitting this field will also use `max`. `standard`, `high`, or other strings may be partially accepted by upstream compatibility but do not guarantee a change in reasoning behavior, so do not rely on them. ```bash curl https://api.acedata.cloud/kimi/chat/completions \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "kimi-k3", "messages": [{"role": "user", "content": "Review this code and provide a fix"}], "reasoning_effort": "max" }' ``` When using the OpenAI SDK, you can directly pass this field: ```python response = client.chat.completions.create( model="kimi-k3", messages=[{"role": "user", "content": "Design a reliable task queue"}], reasoning_effort="max", ) ``` In multi-turn dialogues and tool calls, please return the complete assistant message from the previous round to `messages`, including `reasoning_content` and `tool_calls`. ### Official References - [Thinking Effort](https://platform.kimi.ai/docs/guide/use-thinking-effort): Explains that Kimi K3 always enables reasoning, and the currently supported value for `reasoning_effort` is `max`. - [Model Parameter Reference](https://platform.kimi.ai/docs/api/models-overview): Compares the reasoning parameters, context window, and tool call differences between K3 and K2 series. - [Create Chat Completion](https://platform.kimi.ai/docs/api/chat): Official Moonshot Chat Completions request, response, and OpenAPI field definitions. ## Streaming Response This interface also supports streaming responses, which is very useful for web integration, allowing the webpage to achieve a word-by-word display effect. If you want to return responses in a streaming manner, you can change the `stream` parameter in the request header to `true`. Modify as shown in the figure, but the calling code needs to have corresponding changes to support streaming responses.

After changing `stream` to `true`, the API will return the corresponding JSON data line by line, and we need to make corresponding modifications in the code to obtain the line-by-line results. Python sample calling code: ```python import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"user","content":"Hello"}], "reasoning_effort": "max", "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Below is an excerpt from the starting, reasoning, body, ending, and usage data blocks of a real K3 Max streaming response: ```json data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"","role":"assistant"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"reasoning_content":"The"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":null} data: {"id":"msg_er7WZjyv2kD3TG2yzbFPu5ZJ","object":"chat.completion.chunk","created":1784466598,"model":"kimi-k3","choices":[],"usage":{"prompt_tokens":172,"completion_tokens":168,"total_tokens":340}} data: [DONE] ``` It can be seen that there are many `data` in the response, and the `choices` in `data` are the latest response content, consistent with the content introduced above. `choices` is the newly added response content, and you can interface it into your system based on the results. The end of the streaming response is determined by the content of `data`. If the content is `[DONE]`, it indicates that the streaming response has completely ended. The returned `data` result has multiple fields, which are described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the selected Kimi official model. - `choices`, the response information provided by Kimi for the query. JavaScript is also supported, for example, the streaming call code for Node.js is as follows: ```javascript const options = { method: "post", headers: { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" }, body: JSON.stringify({ "model": "kimi-k3", "messages": [{"role":"user","content":"Hello"}], "stream": true }) }; fetch("https://api.acedata.cloud/kimi/chat/completions", options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` Java sample code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "kimi-k3"); jsonObject.put("messages", [{"role":"user","content":"Hello"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/kimi/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Other languages can be rewritten accordingly; the principle is the same. ## Multi-turn Dialogue If you want to interface the multi-turn dialogue function, you need to upload multiple query words in the `messages` field. The specific examples of multiple query words are shown in the image below:

Python sample call code: ```python import requests url = "https://api.acedata.cloud/kimi/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "kimi-k3", "messages": [{"role":"assistant","content":"Hello! How can I help you today?"},{"role":"user","content":"What model are you?"}], "reasoning_effort": "max" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple query words, you can easily achieve multi-turn dialogue. Below is the actual K3 Max response obtained from this request (unused extended fields omitted): ```json { "id": "msg_Rqp8nPGBDHWwBlL4VpxuafOp", "object": "chat.completion", "created": 1784466628, "model": "kimi-k3", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "I’m Kimi, an AI assistant developed by Moonshot AI (月之暗面). I don’t have a specific public model version identifier to share from here." }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 134, "completion_tokens": 346, "total_tokens": 480 } } ``` It can be seen that the information contained in `choices` is consistent with the content used in basic usage, which includes the specific content of Kimi's responses to multiple dialogues, allowing for corresponding answers to questions based on multiple dialogue contents. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Kimi Chat Completion API to achieve ordinary conversations, streaming responses, multi-turn dialogues, and control the reasoning intensity of K3 through `reasoning_effort`. --- # Kling Videos Generation API Integration Instructions This article will introduce the integration instructions for the Kling Videos Generation API, which can generate official Kling videos by inputting custom parameters. ## Application Process To use the Kling Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, after which you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Kling Videos Generation API →](https://platform.acedata.cloud/documents/kling-videos) ## Basic Usage First, understand the basic usage, which involves inputting the prompt `prompt`, the generation action `action`, the first frame reference image `start_image_url`, and the model `model` to obtain the processed result. You first need to simply pass a field `action` with the value `text2video`, which mainly includes three actions: text-to-video (`text2video`), image-to-video (`image2video`), and video extension (`extend`). Then, we also need to input the model `model`, which currently includes `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, and `kling-o1`, with specific content as follows:

Here we can see that we have set the Request Headers, including: - `accept`: the format of the response result you want to receive, filled in as `application/json`, which means JSON format. - `authorization`: the key to call the API, which can be directly selected after application. Additionally, we set the Request Body, including: - `model`: the model for generating the video, mainly including `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3`, `kling-v3-omni`, and `kling-o1`. - `mode`: the mode for generating the video, with optional values of standard mode `std`, fast mode `pro`, and native 4K mode `4k`. The `4k` mode only supports `kling-v3` and `kling-v3-omni`, and is incompatible with `camera_control` (camera control). - `action`: the action for this video generation task, mainly including three actions: text-to-video (`text2video`), image-to-video (`image2video`), and video extension (`extend`). - `start_image_url`: when selecting the image-to-video action `image2video`, the first frame reference image link must be uploaded. - `end_image_url`: optional for image-to-video, specifies the last frame. - `duration`: video duration, in seconds. `kling-v3` and `kling-v3-omni` support integer durations of 3-15 seconds; `kling-o1` only supports 5 seconds; other models support 5 or 10 seconds. - `generate_audio`: whether to generate audio synchronously, optional, boolean value. Supports `kling-v3`, `kling-v3-omni`, and `kling-v2-6` (only in pro mode). Default is `false`. - `aspect_ratio`: video aspect ratio, optional, supports `16:9`, `9:16`, `1:1`, default is `16:9`. - `cfg_scale`: correlation strength, range [0,1], larger values are more aligned with the prompt. - `camera_control`: optional, controls the parameters for camera movement, supports type/simple presets and configurations such as horizontal, vertical, pan, tilt, roll, zoom, etc. - `negative_prompt`: optional, reverse prompt words that you do not want to appear, up to 200 characters. - `image_list`: Omni reference image list, applicable to models `kling-o1` and `kling-v3-omni`, usage is described in the section "Omni All-Purpose Reference" below. - `video_list`: Omni reference video list (supports video editing), applicable to models `kling-o1` and `kling-v3-omni`, usage is described in the section "Omni All-Purpose Reference" below. - `prompt`: prompt words. - `callback_url`: the URL to receive the callback result. - `async`: optional, when set to `true`, the interface immediately returns `task_id`, no need to provide `callback_url`, and then the result can be polled through the corresponding task query interface. After selection, you can see that the corresponding code is generated on the right side, as shown in the figure:

Click the "Try" button to test, as shown in the above figure, we obtained the following result: ```json { "success": true, "video_id": "900798310464749610", "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.mp4", "duration": "5.041", "state": "succeed", "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5" } ``` The returned result contains multiple fields, described as follows: - `success`, the status of the video generation task at this time. - `task_id`, the ID of the video generation task at this time. - `video_id`, the video ID of the video generation task at this time. - `video_url`, the video link of the video generation task at this time. - `duration`, the duration of the video generation task at this time. - `state`, the status of the video generation task at this time. We can see that we have obtained satisfactory video information, and we only need to access the generated Kling video using the video link address in the `data` result. Additionally, if you want to generate the corresponding integration code, you can directly copy it, for example, the CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-v3", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }' ``` ## Model Capability Matrix Different models have varying support for parameters. The following matrix is organized from the [Kling official video models documentation](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels). Please verify that the current `model` / `mode` / `duration` combination supports the features you need before calling, otherwise it will return errors such as `model/mode/duration(...) is not supported with image_tail`. | Model | Mode | `end_image_url` (First and Last Frame) | `generate_audio` (Accompanying Audio) | `camera_control` (Camera Movement) | Remarks | | ------------------- | -------------- | -------------------- | -------------------- | -------------------- | -------------------------------------------- | | `kling-v1` | std / pro | ✅ Only `duration=5` | ❌ | ✅ Only `duration=5` | `extend` does not support `negative_prompt` and `cfg_scale` | | `kling-v1-6` | std | ❌ | ❌ | ❌ | Multi-image video, `extend` available in all modes | | `kling-v1-6` | pro | ✅ | ❌ | ❌ | | | `kling-v2-master` | — | ❌ | ❌ | ❌ | Single mode, only `duration=5/10` | | `kling-v2-1-master` | — | ❌ | ❌ | ❌ | Single mode, only `duration=5/10` | | `kling-v2-5-turbo` | std | ❌ | ❌ | ❌ | | | `kling-v2-5-turbo` | pro | ✅ | ❌ | ❌ | | | `kling-v2-6` | std | ❌ | ❌ | ❌ | | | `kling-v2-6` | pro | ✅ | ✅ | ❌ | The only non-v3 model that supports accompanying audio | | `kling-v3` | std / pro | ✅ | ✅ | ✅ | `duration` range 3–15 seconds | | `kling-v3` | 4k | ✅ | ✅ | ❌ | 4K mode is incompatible with camera movement | | `kling-v3-omni` | std / pro / 4k | ✅ | ✅ | ❌ | | | `kling-o1` | std / pro | ✅ | ❌ | ❌ | Only supports `duration=5` | Notes: - `mode=4k` is only supported by `kling-v3` and `kling-v3-omni`; it is mutually exclusive with `camera_control`. - `end_image_url` can only be used with `start_image_url` when `action=image2video` is selected. Providing only `end_image_url` (without `start_image_url`) will be rejected. - `kling-v3` / `kling-v3-omni` accept any integer `duration` from 3 to 15 seconds; `kling-o1` only accepts 5; other models only accept 5 or 10. - `generate_audio` defaults to `false`. Only `kling-v3`, `kling-v3-omni`, and `kling-v2-6` (pro mode) support it. ## Video Extension Functionality If you want to continue generating a Kling video that has already been created, you can set the parameter `action` to `extend` and input the ID of the video you want to continue generating. The video ID can be obtained based on basic usage, as shown in the image below:

At this point, you can see that the video ID is: ``` "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c" ``` > Note that the `video_id` here is the ID of the generated video. If you do not know how to generate a video, you can refer to the basic usage mentioned above. Next, we must fill in the prompt for the next step to customize the generated video, specifying the following content: - `model`: The model for generating the video, mainly `kling-v1`, `kling-v1-5`, and `kling-v1-6`. - `mode`: The mode for generating the video, with optional values of standard mode `std`, high-speed mode `pro`, and native 4K mode `4k` (only supported by `kling-v3` and `kling-v3-omni`, incompatible with camera control). - `duration`: The duration of this video generation task, mainly including 5s and 10s. - `start_image_url`: When selecting the image-to-video action `image2video`, the first frame reference image link must be uploaded. - `prompt`: The prompt. An example of filling in is as follows:

After filling it out, the code is automatically generated as follows:

Corresponding Python code: ```python import requests url = "https://api.acedata.cloud/kling/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "extend", "model": "kling-v1", "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "duration": 10 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Clicking run, you can see that a result is obtained, as follows: ```json { "success": true, "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4", "duration": "9.6", "state": "succeed", "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23" } ``` It can be seen that the result content is consistent with the above, thus achieving the video extension functionality. ## Omni All-Purpose Reference (Video Editing / Reference Video / Multi-Image Reference) `kling-o1` and `kling-v3-omni` are two independent models, both supporting "all-purpose reference" capabilities. Based on text-to-video (`action=text2video`), additional reference images or videos can be provided to achieve **multi-image reference, reference video, and direct editing of existing videos**. **Core Agreement**: Reference materials must be referenced in the `prompt` in the form of `<<>>`, `<<>>` (with numbering starting from 1) corresponding to the positions in `image_list` / `video_list`, for the model to apply these references. If materials are provided without being referenced in the prompt, they will be ignored. > Safety Note: The current API does not open `element_list`. The IDs of the Kling Element Library are not tenant-isolated. Please use `image_list` to provide the main reference image until a tenant-isolated Element Management API is provided. Omni requests do not support `negative_prompt`, `cfg_scale`, or `camera_control`, and cannot use `mode=4k`. When including reference videos, `generate_audio` must be `false`. ### Reference Video and Video Editing (`video_list`) `video_list` is used to pass in reference videos, which is the most commonly used scenario for this capability. The array element fields are as follows: - `video_url`: Reference video link, cannot be empty. Requirements: format MP4/MOV; resolution 720px–2160px; duration 3–10 seconds; frame rate 24–60fps; file size ≤200MB; up to 1 video. - `refer_type`: Reference type, optional `base` (default, **editable base video**, i.e., "directly edit the video", can add/delete/modify elements, change composition, change style, change color, change weather, etc.) or `feature` (**feature reference**, reference its style / camera movement / continue to the next shot). - `keep_original_sound`: Whether to keep the original video audio, optional `yes` (keep) or `no` (remove). > Note: When a reference video exists, `generate_audio` must be `false`. Videos with `refer_type=base` cannot specify the first frame / last frame. An example of CURL for editing an existing video (changing the video to an anime style) is as follows: ```shell curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Change <<>> to a movie-level anime style, keeping the original movement and composition", "video_list": [ { "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4", "refer_type": "base", "keep_original_sound": "no" } ] }' ``` ### Multi-image Reference (`image_list`) `image_list` is used to pass in reference images (elements / scenes / styles, etc.), the array element fields are as follows: - `image_url`: Reference image link, cannot be empty. Requirements: format .jpg/.jpeg/.png; file size ≤10MB; shortest side ≥300px; aspect ratio 1:2.5 ~ 2.5:1. - `type`: Optional. If not provided, treated as a pure reference image; if `first_frame` / `end_frame` is provided, it is treated as the first frame / last frame (equivalent to `start_image_url` / `end_image_url`). When using, it should be referenced in `prompt` as `<<>>`, `<<>>`. Quantity limit: if there is no reference video, reference images ≤ 7; if there is a reference video, reference images ≤ 4. If only the first / last frame is provided, `start_image_url` / `end_image_url` can also be used directly, but the last frame must be used together with the first frame. > Note: If both `start_image_url` / `end_image_url` and `image_list` are provided, the first / last frame will be placed before `image_list`, which may affect the corresponding relationship of `<<>>`. It is recommended to choose one: if first / last frames are needed, specify directly in `image_list` using `type`, do not mix with `start_image_url` / `end_image_url`. An example of CURL for generating a video with multi-image reference: ```shell curl -X POST 'https://api.acedata.cloud/kling/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "kling-o1", "mode": "std", "duration": 5, "prompt": "Let the character in <<>> stand in the scene of <<>>, cinematic lighting", "image_list": [ { "image_url": "https://cdn.acedata.cloud/subject.png" }, { "image_url": "https://cdn.acedata.cloud/scene.png" } ] }' ``` ## Asynchronous Callback Due to the relatively long generation time of the Kling Videos Generation API, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the result of the generated video will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let's understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For convenience, a public Webhook sample site https://webhook.site/ is used for demonstration. Opening this site will provide a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/tbcnai.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`. Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the image:

Clicking run, you will immediately receive a result, as follows: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` After a moment, we can observe the generated video result at `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, as shown in the image: ![](https://cdn.acedata.cloud/zv5u2q.png) The content is as follows: ```json { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` It can be seen that the result contains a `task_id` field, and the other fields are similar to those mentioned above, allowing the task to be associated through this field. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Kling Videos Generation API to generate videos by inputting prompt words and a reference image for the first frame. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Maestro Video Generation API Integration Instructions Maestro is a **native Agent** video production interface: you describe the desired video in a natural language `prompt` (optionally attaching reference images/videos/audios with `file_urls`), and a headless "AI director" will automatically complete the topic selection, script writing, scene generation, voiceover, music, synthesis, and rendering, ultimately producing a subtitled final product and uploading it to the CDN. This article will provide detailed instructions for integrating the Maestro video generation API, helping you quickly integrate and fully utilize the capabilities of this API. This is an **asynchronous task** interface: after submission, it will immediately return a `task_id`, and you can then poll for results through the [Maestro Task Query API](development_maestro_tasks.md) (`POST /maestro/tasks`) (polling is free of charge). To continue iterating on an existing video, you can use `action: remix` / `edit` / `extend` along with `ref_task_id`. ## Application Process To use the Maestro video generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform, without needing to apply separately for each service.** The first application will grant free credits for a trial experience; when credits are insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Maestro Video Generation API →](https://platform.acedata.cloud/documents/maestro-videos) ## Basic Usage `POST https://api.acedata.cloud/maestro/videos` The most basic usage requires only passing in a natural language `prompt`, and the AI director will automatically decide on the script, scenes, voiceover, and editing. Here we will first understand the request headers and request body that need to be set. **Request Headers** include: - `accept`: the format of the response you want to receive, here it is filled as `application/json`, which means JSON format. - `authorization`: the key to call the API, which can be directly selected after application. - `content-type`: the format of the request body, here it is filled as `application/json`. **Request Body** mainly includes: - `prompt`: a natural language description of the video to be made (theme, what to showcase, style, audience). - `langs`: an array of output languages, such as `["zh-cn", "en"]`, default is `["zh-cn"]`. - `aspect`: aspect ratio, `9:16` (default) / `16:9` / `1:1`. - `duration`: target duration (seconds), default is 30. The complete fields of the request body are shown in the table below: | Field | Type | Required | Description | | -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | Yes | A natural language description of the video to be made (theme, what to showcase, style, audience). The script, scenes, voiceover, and editing are all determined by AI | | `action` | string | No | `generate` (default, generate a new video) / `remix` / `edit` / `extend` (iterate on an existing video, must be used with `ref_task_id`) | | `ref_task_id` | string | No | Required when `action` is remix / edit / extend: the historical task `task_id` as a starting point | | `file_urls` | string[] | No | Reference media (image / video / audio URLs), such as product images, logos, or material clips to add subtitles | | `langs` | string[] | No | Output languages, such as `["zh-cn", "en"]`, default is `["zh-cn"]`. The first is the primary language; for each additional language, reuse the scenes, only add voiceover + rendering, **each additional +6 points** | | `aspect` | string | No | `9:16` (default) / `16:9` / `1:1`. Lite outputs 720p/24fps, Standard and Pro output 1080p/30fps | | `duration` | int | No | Target duration (seconds), default is 30. Lite is **5–30 seconds**, Standard is **5–120 seconds**, Pro is **5–300 seconds**. Charged based on the actual final video duration, but will not exceed the requested duration | | `quality` | string | No | Production level: `lite` (quick short video, 0.20 points/second) / `standard` (default, balanced production, 0.60 points/second) / `pro` (high-end production, 1.20 points/second) | | `scenario` | string | No | Video type: Lite supports `auto` / `narrated` / `captions`; Standard adds `avatar`; Pro adds `drama`. `captions` requires the source video, `avatar` requires a portrait | | `style` | string | No | Visual style presets: `auto` (default) / `cinematic` / `glass` / `luxury` / `swiss` / `modern` / `editorial` / `warm` / `vibrant` / `neon` / `mono` / `pastel` / `bold` / `industrial` / `futuristic` / `retro`, also accepts free text as a soft prompt. Orthogonal to `scenario`, does not change routing | | `voice` | string | No | Voiceover tone (independent of language, cross-language applicable): `auto` (default) / `warm-female` / `bright-female` / `anchor-female` / `clean-female` / `calm-male` / `deep-male` / `documentary-male` / `energetic-male` / `storyteller-male` | Below is a specific example to demonstrate. Suppose we want to generate a bilingual Chinese-English, vertical, 20-second science popularization short video, the corresponding CURL code is as follows: ```bash curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, and end with a memorable point", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 }' ``` The corresponding Python code is as follows: ```python import requests url = "https://api.acedata.cloud/maestro/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "prompt": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, and end with a memorable point", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Click to run, and you will find that you immediately get a result, as follows: ```json { "success": true, "task_id": "f57e99c4f60f4373a15517742ce2357d", "trace_id": "70e1cb12-c619-4292-a416-90191205996b" } ``` The fields in the returned result are described as follows: - `success`: Whether the task was successfully submitted. - `task_id`: The ID of this video generation task, which will be used to poll for results via the [Maestro Task Query API](development_maestro_tasks.md). - `trace_id`: The tracking ID of this request, which can be provided to technical support for troubleshooting. Since video production takes a long time, the interface **immediately returns `task_id`** and does not wait for the video rendering to complete. Next, you need to use `task_id` to poll for results, see the "Get Results" section for details. ## Specify Video Type and Style (scenario / style) If `scenario` is not provided, AI will automatically determine it (equivalent to `auto`); if you want to pin the video to a certain type, you can explicitly pass it. For example, to create a **vertical short drama**, you can specify the following content: - `scenario`: Video type, set to `drama` (a short drama with characters + dialogue). - `style`: Visual style, set to `cinematic` (film quality). The sample CURL code is as follows: ```bash curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "Two co-renting roommates fall out and reconcile over a cat, with three acts of reversal and a warm ending", "scenario": "drama", "style": "cinematic", "aspect": "9:16", "duration": 40 }' ``` Common combinations: - Narrated short video: `scenario: "narrated"`, supported by Lite / Standard / Pro. - Automatic subtitles: `scenario: "captions"`, requires `file_urls` to pass the source video, supported by Lite / Standard / Pro. - Digital human / voiceover: `scenario: "avatar"`, requires `file_urls` to pass a portrait, supported by Standard / Pro. - Short drama: `scenario: "drama"` (characters + dialogue), supported only by Pro. - `style` is a visual style preset (such as `modern` / `neon` / `luxury`), which does not change the type but only affects the visual experience. - `voice` is used to specify the tone of the narration (such as `warm-female` / `deep-male`), independent of language and applicable across languages. The returned result is the same as "Basic Usage," also immediately returning `task_id`. ## Multilingual Output By passing multiple languages in `langs`, you can produce multilingual versions at once. The first is the main language, and for each additional language, it will **reuse the same set of visuals**, only adding voiceovers + rendering, so **each additional language only adds +6 points**. Example: ```bash curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "prompt": "Introduce our intelligent customer service product, highlighting 3 core selling points", "langs": ["zh-cn", "en", "ja"], "aspect": "16:9", "duration": 30 }' ``` After the task is completed, each language will correspond to a `variant` in the result (see [Maestro Task Query API](development_maestro_tasks.md)). ## Iterate on Existing Videos (remix / edit / extend) By passing `action` and the previous task's `ref_task_id`, you can make differential modifications based on the original project (such as "change the title of Act 2" or "change the voiceover" or "darken the overall tone"). Small changes are quick, while large changes will require a redo: ```bash curl -X POST 'https://api.acedata.cloud/maestro/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "remix", "ref_task_id": "f57e99c4f60f4373a15517742ce2357d", "prompt": "Change the opening title to something more impactful, and darken the overall color scheme" }' ``` - `remix`: Reinterpret the original video structure (retain the theme, adjust the presentation). - `edit`: Make fine-tuning to specific parts (such as changing titles, voiceovers, color grading). - `extend`: Expand content based on the original video. The returned result will also immediately return a new `task_id`, which can be used to poll for the final product after iteration. ## Get Results Since video production takes a long time, this interface immediately returns `task_id` after submission, and you need to use it to poll for results via the [Maestro Task Query API](development_maestro_tasks.md): ```bash curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "f57e99c4f60f4373a15517742ce2357d" }' ``` When the task is completed, it will return the final product information (each language corresponds to a `variant`). The `status` will go through `pending → planning → producing → succeeded` (or `failed`), **polling is free and does not consume points**. For the complete response format and historical list query, please refer to the [Maestro Task Query API Integration Guide](development_maestro_tasks.md). ## Billing **Billing is based on the actual final product after the task is completed, and failed tasks are not charged.** Billing is based on the actual delivered product duration and the number of languages, and the billed duration will not exceed the requested duration. If a certain language ultimately does not produce a result, the +6 surcharge for that language will not be charged. Submitting a task itself is not charged separately, and `/maestro/tasks` polling is free. The points for a single final product are calculated as follows: ``` Points = Final product duration in seconds × SKU price per second × scenario multiplier + 6 × max(number of languages - 1, 0) ``` | SKU | Price per Second | Maximum Duration | Output | Scenarios and Actions | | ---------- | ------: | ----: | ----------------- | ------------------------------------ | | `lite` | 0.20 points | 30 seconds | 720p / 24fps | auto, narrated, captions; generate, edit | | `standard` | 0.60 points | 120 seconds | 1080p / 30fps | add avatar; add remix | | `pro` | 1.20 points | 300 seconds | 1080p / 30fps high bitrate | add drama; add extend | Scene multipliers: `drama` 1.35× / `avatar` 1.15× / others 1×. | Example | Points | | ------------------- | --: | | Lite 30 seconds | 6 | | Standard 30 seconds | 18 | | Standard 60 seconds | 36 | | Standard 120 seconds | 72 | | Pro 30 seconds | 36 | | Pro 300 seconds | 360 | | For each additional actual delivery language | +6 | | `/maestro/tasks` polling | Free | ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 invalid_request`: Bad request, possibly due to a missing `prompt` or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `403 forbidden`: Forbidden, insufficient balance or access. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Maestro video generation API: with just a natural language `prompt`, you can automatically complete scripts, materials, voiceovers, music, editing, subtitles, and rendering, and support specifying video types, styles, tones, multilingual output, and iterating on existing videos. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. ## Related Interfaces - [Maestro Task Query API Integration Instructions](development_maestro_tasks.md): Use `POST /maestro/videos` to return the `task_id` to query task status and results, or pull the historical task list (polling is free). --- # MiniMax H3 Video Generation API Integration Guide This article introduces the integration and usage of the MiniMax H3 Video Generation API. This interface supports text-to-video generation, control of the first and last frames, and multi-modal reference video generation, using a unified V2 multi-modal `content` structure to create tasks. ## Application Process To use the MiniMax H3 Video Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and will return to the current page automatically after completion. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant free credits for a trial experience; when credits are insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [MiniMax H3 Video Generation API →](https://platform.acedata.cloud/documents/minimax-videos-integration) It is recommended to save the Token as an environment variable and not to write it into the source code or submit it to the version control system: ```bash export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Interface Overview - **Base URL**: `https://api.acedata.cloud` - **Endpoint**: `POST /minimax/videos` - **Authentication Method**: Include `authorization: Bearer {token}` in the HTTP Header - **Request Headers**: - `accept: application/json` - `content-type: application/json` - **Model**: `MiniMax-H3` - **Input Structure**: Pass text, images, videos, and audio through the unified `content` - **Output Mode**: By default, wait synchronously for generation to complete and return the complete `task`; change to asynchronous by passing `async: true` or `callback_url` - **Result Query**: Asynchronous mode or historical tasks can query status and completed videos through the [MiniMax H3 Task Query API](/documents/minimax-tasks-integration) - **Asynchronous Callback**: Optional, receive the final task result via `callback_url` You do not need to pass `action` to select the generation mode; the interface will automatically determine the purpose based on the material types and `role` in `content`. ## Suitable Scenarios | Scenario | Input Combination | Common Uses | | ---------------- | ---------------------------------- | -------------------------------- | | Text-to-Video | Text | Advertising creativity, storyboard rehearsal, short videos, atmospheric shots | | First Frame to Video | Text + First Frame Image | Make product images, posters, character photos, or illustrations come to life naturally | | Last Frame / First and Last Frame Video | Text + Last Frame, or Text + First Frame + Last Frame | Control the opening and closing, transitions, growth changes, and before-and-after comparisons | | Multi-modal Reference Video | Text + Reference Image / Video / Audio | Maintain consistency in characters and products, replicate actions, camera movements, audio tones, or editing rhythms | ## Calling Process In the default synchronous mode, after calling `/minimax/videos`, keep the connection open; when generation is complete, directly obtain the video from the response's `task.content.url`. To release the connection immediately, pass `async: true` or `callback_url`: 1. Save the `task_id` and `trace_id` from the immediate response. 2. If no callback is configured, call `/minimax/tasks` every 10 seconds to check. 3. When `task.status` changes to `succeeded`, obtain the video from `task.content.url`. 4. Stop polling when the status is `failed` or `cancelled`, and read `task.error`. ## Top-Level Request Parameters | Parameter | Type | Required | Default Value | Description | | ---------------- | --------- | -------- | ------------- | ---------------------------------------------------- | | `model` | string | Yes | - | Fixed as `MiniMax-H3` | | `content` | object[] | Yes | - | Multi-modal content array, must contain one non-empty `text` item | | `resolution` | string | Yes | - | `768P` or `2K` | | `duration` | integer | Yes | - | Generation duration, an integer between 4-15 seconds | | `ratio` | string | Conditionally Required | `adaptive` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | | `async` | boolean | No | `false` | `false` returns complete results synchronously; `true` returns task identifier immediately, then results can be obtained through the task query interface | | `callback_url` | string | No | - | Public callback URL to receive the final task result; automatically enables asynchronous mode when provided | The rules for `ratio` depend on the workflow: - **Text-to-Video**: Required and cannot be `adaptive`. - **First Frame, Last Frame, or First and Last Frame Video**: The aspect ratio is determined by the input image; it is recommended to omit or pass `adaptive`. - **Multi-modal Reference Video**: Can be omitted, default is `adaptive`; a fixed ratio can also be explicitly specified. The interface does not accept legacy or compatible fields such as `prompt`, `image_urls`, `audio_urls`, `messages`, and `first_frame_image`. When receiving such parameter errors, please remove the old fields and migrate to `content`; for example, change `"prompt": "A cat waving"` to `"content": [{"type": "text", "text": "A cat waving"}]`. Do not send both new and old formats simultaneously. ## Content Item Parameters Each content item must have `type`, and the other fields are determined by the type: | `type` | Data Field | `role` | Description | | ------------- | --------------------- | ----------------- | --------------------------------------------- | | `text` | `text` | Not passed | Each request must contain one non-empty text item, up to 7000 characters | | `image_url` | `image_url.url` | `first_frame` | First frame image; if there is only one image and `role` is omitted, it is also treated as the first frame | | `image_url` | `image_url.url` | `last_frame` | Last frame image; can be used alone or combined with `first_frame` to control the start and end | | `image_url` | `image_url.url` | `reference_image` | Reference subject, character, product, clothing, scene, or style | | `video_url` | `video_url.url` | `reference_video` | Reference action, camera movement, performance, or editing structure | | `audio_url` | `audio_url.url` | `reference_audio` | Reference audio tone, dialogue, music, or rhythm | Media addresses support three forms: - Publicly accessible HTTPS URL, recommended for large files. - `mm_file://{file_id}`, referencing files that have already been uploaded or have existing results. - Base64 data URI corresponding to the media type. Base64 will increase the size by about one-third, please ensure the entire request body does not exceed 64 MB. ## Material Specifications and Quantity Limits | Material | Format | Single File Limit | Size / Duration | Quantity Limit | | --- | ------------------------------------------- | --------- | --------------------------------------------------------------- | --------------------------- | | Image | JPG, JPEG, PNG, WEBP, HEIC, HEIF | Up to 30 MB | Width and height both between 256-5760 px; aspect ratio 0.4-2.5 | Up to 1 first frame, up to 1 last frame, up to 9 reference images | | Video | MP4, MOV; H.264/AVC or H.265/HEVC; audio track AAC or MP3 | Up to 50 MB | Each segment 2-15 seconds, total not exceeding 15 seconds; width and height both between 256-5760 px; aspect ratio 0.4-2.5; 23.976-60 fps | Up to 3 segments of reference video | | Audio | WAV, MP3 | Up to 15 MB | Each segment 2-15 seconds, total not exceeding 15 seconds | Up to 3 segments of reference audio | In multimodal reference scenarios, the total number of images, videos, and audios is limited to 12 files. First and last frame scenarios and reference material scenarios are mutually exclusive: once `reference_image`, `reference_video`, or `reference_audio` is used, `first_frame` or `last_frame` cannot be used, and vice versa. ## Production-Level Capability Demonstration The following are not concept images or placeholder materials, but real reference inputs and actual video outputs of the MiniMax H3 official production-level capability samples. The three sets of cases cover brand short films, live-action narratives, and fashion e-commerce, suitable for evaluating the model's most critical capabilities in commercial production. | Capability | Key Observations | | -------- | --------------------------- | | Consistency of Characters and Faces | Stability of facial features, hairstyle, makeup, and character temperament after multiple camera switches | | Facial Performance | Eye contact, micro-expressions, emotional tension, and natural head movement in close-ups | | Product Structure Retention | Contours, materials, wearing relationships, and mirror reflections of products like glasses and handbags | | Brand Visual Execution | Consistency of scene atmosphere, film grain, colors, logo, and editing rhythm | | Cinematic Narrative | Ability to form complete segments through changes in shot distance, character staging, camera movement, rhythm, and sound | Here, "facial capability" refers to the consistency of character appearance, facial details, and performance control in video generation, not identity recognition, face comparison, or face-swapping interfaces. ### High-End Brand Short Film: Unity of Characters, Products, and Brand Assets **Production Goal:** 16:9 high-end fashion brand film. Establish a stark atmosphere with a desert road and vintage cars, maintaining the appearance of the female lead and the structure of the black handbag, and naturally incorporating the brand logo at the end. This case focuses on testing cross-shot character consistency, product retention, cinematic quality, and brand cohesion. | Atmosphere and Scene Reference | Character Reference | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Desert road and vintage car brand film atmosphere reference | Brand film female lead reference | | Handbag Product Reference | Brand Logo Reference | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Black handbag product reference | Brand logo reference | [Directly open or download the brand short film](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a) The corresponding `content` organization is as follows: ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "15 seconds, 16:9 high-end fashion brand film. A vintage car parked by a desert road, the female lead takes a black handbag from the trunk, briefly makes eye contact with the male lead, and leaves alone. Maintain consistency of characters, handbag, and brand visuals; stark and high-end, cinematic grain, crisp editing, and naturally present the brand logo at the end." }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" }, "role": "reference_image" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" }, "role": "reference_image" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" }, "role": "reference_image" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" }, "role": "reference_image" } ], "resolution": "2K", "duration": 15, "ratio": "16:9" } ``` ### Live-Action Vertical Short Drama: Face Consistency and Emotional Performance **Production Goal:** 15 seconds, 9:16 dark romantic short drama trailer. Lock in character appearance through reference images of the male and female leads, and constrain the space with reference images of a castle; use medium close-ups and facial close-ups to express eye confrontations, fear, restraint, and a sense of danger. This case is suitable for observing the stability of human facial features, micro-expressions, gaze relationships, and continuous performances. | Male and Female Lead References | Castle Scene References | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Live-action short drama male and female lead references | Dark castle scene references | [Directly open or download the live-action short drama](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf) The prompt should clearly define the character relationships, emotions, and shot types, rather than just describing "dialogue between a man and a woman": ```text 15 seconds, 9:16 live-action dark romantic short drama trailer. The female lead accidentally enters a forbidden castle, awakening a sleeping vampire noble; he approaches dangerously and restrained, while she is fearful but does not yield. Maintain consistency in the facial features, hairstyles, and costumes of both characters, using medium close-ups and facial close-ups to express eye confrontations and emotional tension, with dark **###** lighting and a tight rhythm. ``` ### Fashion Glasses Advertisement: Maintain Facial Details and Product Structure **Production Goal:** 9:16 high-end fashion glasses advertisement. Full-body images of characters are responsible for body shape and walking, facial reference images are responsible for facial features and makeup, and product images are responsible for surrounding curves, lens reflections, temples, and cat-eye outlines. This case tests facial close-ups, consistency among multiple people, wearing relationships, and product geometric structures. | Model and Styling References | Facial Detail References | Glasses Product References | | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Fashion advertisement model and styling references | Model facial detail references | Glasses product structure references | [Directly open or download the fashion glasses advertisement](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751) In product advertisements, the prompt should clearly separate the responsibilities of character references and product references: character materials constrain the face, makeup, body shape, and temperament; product materials constrain the outline, material, reflection, and wearing position. This is more stable than vaguely writing "generate a glasses advertisement." ## Text-to-Video When there is only one text item, it is a text-to-video. It is suitable for directly generating images from creative, script, or shot descriptions. The prompt can be organized in the order of "subject + action + scene + shot + lighting + sound." ```bash curl -X POST 'https://api.acedata.cloud/minimax/videos' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "15 seconds cinematic perfume advertisement: On the black rocks of the coast in the morning, a transparent perfume bottle is surrounded by mist and waves. A close-up showcases water droplets on the bottle and glass refraction, with the camera slowly pulling up from the product close-up to the vast sea; silver-blue tones, real natural light, high-end restraint, ending with a freeze on the product." } ], "resolution": "2K", "duration": 15, "ratio": "16:9" }' ``` Default synchronous response: ```json { "task": { "id": "f5977217-ed2c-40da-adbe-93d08235618f", "model": "MiniMax-H3", "status": "succeeded", "content": { "url": "https://cdn.acedata.cloud/minimax/f5977217-ed2c-40da-adbe-93d08235618f.mp4" }, "resolution": "2K", "duration": 15, "usage": { "total_seconds": 15, "input_seconds": 0, "output_seconds": 15, "input_image_count": 0 }, "ratio": "16:9", "task_type": "generation", "modality": "video" } } ``` If the request includes `"async": true`, the interface immediately returns: ```json { "task_id": "f5977217-ed2c-40da-adbe-93d08235618f", "trace_id": "trace_7f8c2b1a" } ``` ## First Frame Image to Video Mark the image as `first_frame`, and the model will start generating from that frame. It is suitable for making posters, product images, character design images, and photographic works come to life naturally. ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "The character breathes naturally and looks out the window, the corners of the clothes are blown by the breeze, the camera slowly moves in." }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/b1c82e4937.png" }, "role": "first_frame" } ], "resolution": "2K", "duration": 5, "ratio": "adaptive" } ``` ## Last Frame and First and Last Frame Video Providing only `last_frame` allows the model to naturally generate to the specified image; at the same time, providing both `first_frame` and `last_frame` can clearly control the starting and ending points. Suitable for transitions, shape changes, growth processes, or product comparisons before and after. ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "The girl naturally grows from childhood to youth, time flows smoothly, and the character remains in the center of the frame." }, { "type": "image_url", "image_url": { "url": "YOUR_FIRST_FRAME_URL" }, "role": "first_frame" }, { "type": "image_url", "image_url": { "url": "YOUR_LAST_FRAME_URL" }, "role": "last_frame" } ], "resolution": "2K", "duration": 5, "ratio": "adaptive" } ``` The dimensions and aspect ratios of the first and last frames should be as consistent as possible, and the differences in subject position, composition, and lighting should not be too large, making it easier to achieve a natural transition. ## Multi-modal Reference Live Video Reference materials can be used in combination: reference images control the appearance of characters or products, reference videos control actions and camera movements, and reference audio controls dialogue tone, music, or editing rhythm. The prompt should clearly specify what each type of material is meant to control, avoiding the upload of materials without providing the relationship. ```json { "model": "MiniMax-H3", "content": [ { "type": "text", "text": "Keep the facial features, hairstyle, and clothing of the reference character consistent, and complete the fashion short film according to the performance actions in the reference video; the camera rhythm follows the reference audio, with close-ups highlighting natural facial expressions." }, { "type": "image_url", "image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" }, "role": "reference_image" }, { "type": "video_url", "video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" }, "role": "reference_video" }, { "type": "audio_url", "audio_url": { "url": "YOUR_AUDIO_URL" }, "role": "reference_audio" } ], "resolution": "2K", "duration": 5, "ratio": "adaptive" } ``` ## Callback Notification Passing in `callback_url` will automatically enable asynchronous mode: the creation interface immediately returns `task_id` and `trace_id`, and after the task is completed, it POSTs the final result to that address, with a structure consistent with the task query response. The final status in the callback is `succeeded`, `failed`, or `cancelled`. Even when using callbacks, it is recommended to save `task_id` for proactive queries or to compensate for missed notifications. ## Common Errors | HTTP Status Code | Meaning | Handling Suggestions | | -------- | ------------ | ------------------------------ | | `400` | Parameter error or invalid material combination | Check required fields, `role`, material quantity, and format | | `401` | Token missing or invalid | Check `Authorization: Bearer ...` | | `402` | Insufficient balance or quota | Supplement general balance in the console | | `422` | Content security check failed | Adjust prompts or materials and resubmit | | `429` | Too many requests | Retry after exponential backoff; task polling is recommended to be about 10 seconds apart | | `500` | Service temporarily unavailable | Retain request information and retry later | In synchronous responses, `task.status: succeeded` indicates that the video has been generated; asynchronous confirmation only means the task has entered the queue. Only when the task is ultimately successful will it be billed; querying the task itself is free and will not incur repeated charges. --- # Nano Banana Images API Integration Instructions This document introduces the integration and usage of the Nano Banana Images API. This interface supports two capabilities: **image generation (generate)** and **image editing (edit)**. ## Application Process To use the Nano Banana Images API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images) ## Interface Overview - **Base URL**: `https://api.acedata.cloud` - **Endpoint**: `POST /nano-banana/images` - **Authentication Method**: Include `authorization: Bearer {token}` in the HTTP Header - **Request Headers**: - `accept: application/json` - `content-type: application/json` - **Actions**: - `generate`: Generate images based on text prompts - `edit`: Edit based on given images - **Models** (optional): - `nano-banana` (default): Based on Gemini 2.5 Flash Image, fast speed, low cost - `nano-banana-2-lite`: Based on Gemini 3.1 Flash Lite Image, supports only 1K, fast generation speed - `nano-banana-2`: Based on Gemini 3.1 Flash Image Preview, Pro-level quality + Flash speed - `nano-banana-pro`: Based on Gemini 3 Pro Image Preview, highest quality - `nano-banana:official`, `nano-banana-2-lite:official`, `nano-banana-2:official`, `nano-banana-pro:official`: Official channel versions of the corresponding models, better image quality and stability, different billing - **Asynchronous Callback**: Optional, receive task completion notifications and results via `callback_url` - **Number of Images**: Optional, specify 1–4 images via `count`, default is 1; if some fail, only successful images will be returned and billed ## Quick Start: Generate Image (`action=generate`) **Minimum Required Parameters**: `action`, `prompt` When you only want to generate an image based on a prompt, set `action` to `generate` and provide a clear `prompt`. ### Request Example (cURL) ```bash curl -X POST 'https://api.acedata.cloud/nano-banana/images' \ -H 'authorization: Bearer {token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "nano-banana-pro", "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.", "count": 1 }' ``` ### Request Example (Python) ```python import requests url = "https://api.acedata.cloud/nano-banana/images" headers = { "authorization": "Bearer {token}", "accept": "application/json", "content-type": "application/json", } payload = { "action": "generate", "model": "nano-banana-pro", "prompt": ( "A photorealistic close-up portrait of an elderly Japanese ceramicist " "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully " "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched " "workshop. The scene is illuminated by soft, golden hour light streaming through " "a window, highlighting the fine texture of the clay. Captured with an 85mm " "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood " "is serene and masterful. Vertical portrait orientation." ), "count": 1 } resp = requests.post(url, json=payload, headers=headers) print(resp.json()) ``` ### Successful Response Example ```json { "success": true, "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04", "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2", "data": [ { "prompt": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.", "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png" } ] } ``` ### Field Explanation - `success`: Whether the request was successful. - `task_id`: Task ID. - `trace_id`: Link tracking ID, useful for troubleshooting. - `count`: The number of images requested for generation or editing, supports 1–4, default is 1. If some fail, `data` only contains successful images. - `data[]`: Result list. - `prompt`: The prompt used for generation (echo). - `image_url`: Direct URL of the generated image. > Note: Only `action` and `prompt` are required to generate an image at `/nano-banana/images` ## Edit Image (`action=edit`) When you want to edit based on an existing image, set `action` to `edit`, and pass the list of image URLs to be edited through `image_urls` (1 or more), while also providing a `prompt` describing the editing goal. For example, if we provide a photo of a person and a photo of a shirt, we can have the person wear that shirt by passing the image URLs and specifying the action as `edit`. The URLs can be HTTP URLs, publicly accessible links using `https` or `http` protocols, or Base64 encoded images, such as `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....` ### Request Example (cURL) ```bash curl -X POST 'https://api.acedata.cloud/nano-banana/images' \ -H 'authorization: Bearer {token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "action": "edit", "prompt": "let this man wear on this T-shirt", "image_urls": [ "https://cdn.acedata.cloud/v8073y.png", "https://cdn.acedata.cloud/44xlah.png" ], "count": 1 }' ``` ### Request Example (Python) ```python import requests url = "https://api.acedata.cloud/nano-banana/images" headers = { "authorization": "Bearer {token}", "accept": "application/json", "content-type": "application/json", } payload = { "action": "edit", "prompt": "let this man wear on this T-shirt", "image_urls": [ "https://cdn.acedata.cloud/v8073y.png", "https://cdn.acedata.cloud/44xlah.png" ], "count": 1 } resp = requests.post(url, json=payload, headers=headers) print(resp.json()) ``` ### Example of Successful Return ```json { "success": true, "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3", "trace_id": "a9063166-26ed-4451-85b5-54e896817c69", "data": [ { "prompt": "let this man wear on this T-shirt", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png" } ] } ``` ### Field Description - `image_urls[]`: List of image URLs to be edited (must be publicly accessible). Multiple images can be sent, and the service will combine these materials with the `prompt` to complete the editing. - Other fields are the same as the "Generate Image" return. --- ## Asynchronous Callback (Optional, Recommended) Generation or editing may take some time. To avoid long connections occupying resources, it is recommended to use **Webhook Callback** via `callback_url`: 1. Add `callback_url` in the request body, for example, your server's Webhook address (must be publicly accessible and support POST JSON). 2. The API will **immediately return** a response containing the `task_id` (or basic results). 3. When the task is completed, the platform will send the complete JSON to the `callback_url` via `POST`. You can associate the request with the result using the `task_id`. **Callback Payload Example** (Field structure is consistent with synchronous successful return): ```json { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": [ { "prompt": "a white siamese cat", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png" } ] } ``` --- ## Error Handling When the call fails, a standard error format and trace ID will be returned. Common errors are as follows: - **400 `token_mismatched`**: The request is invalid or parameters are incorrect. - **400 `api_not_implemented`**: The interface is not implemented (please contact support). - **401 `invalid_token`**: Authentication failed or token is missing. - **429 `too_many_requests`**: Request frequency limit exceeded. - **500 `api_error`**: Server exception. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "Internal server error." }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` --- ## Parameter Correspondence and Notes - **Required**: `action`, `prompt` - **Editing Specific**: `image_urls` (array, at least 1 item) - **Optional**: `model` (default `nano-banana`, optional `nano-banana-2-lite`, `nano-banana-2`, `nano-banana-pro`, or corresponding `:official` official channel version), `aspect_ratio` (width-to-height ratio, such as `1:1`, `16:9`), `resolution` (resolution, such as `1K`, `2K`, `4K`; `nano-banana-2-lite` only supports `1K`), `callback_url` (for asynchronous callback) - **Headers**: Must provide `authorization: Bearer {token}`; `accept` is recommended to be set to `application/json` - **Image Accessibility**: `image_urls` must be direct links that are publicly accessible (HTTP/HTTPS), HTTPS is recommended - **Idempotency and Tracking**: Retain `task_id` and `trace_id` for troubleshooting and result association. --- # OpenAI Chat Completion API Application and Usage OpenAI ChatGPT is a very powerful AI dialogue system that can generate smooth and natural replies in just a few seconds by inputting prompts. ChatGPT stands out in the industry with its excellent language understanding and generation capabilities, and today, it has been widely applied across various industries and fields, with its influence becoming increasingly significant. Whether for daily conversations, creative writing, or professional consulting and coding, ChatGPT can provide astonishing intelligent assistance, greatly enhancing human work efficiency and creativity. This document mainly introduces the usage process of the OpenAI Chat Completion API, allowing us to easily utilize the dialogue features of the official OpenAI ChatGPT. ## Application Process To use the OpenAI Chat Completion API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a free experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [OpenAI Chat Completion API →](https://platform.acedata.cloud/documents/openai-chat-completions) ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, we need to fill in at least three pieces of content: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the category of the OpenAI ChatGPT model we choose to use; here we mainly have 20 types of models, and details can be found in the models we provide. The last parameter is `messages`, which is an array of our input questions; it is an array that allows multiple questions to be uploaded simultaneously, with each question containing `role` and `content`, where `role` indicates the role of the questioner, and we provide three identities: `user`, `assistant`, and `system`. The other `content` is the specific content of our question. You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing. Common optional parameters: - `max_tokens`: Limits the maximum number of tokens for a single reply. - `temperature`: Generates randomness, between 0-2, with larger values being more divergent. - `n`: How many candidate replies to generate at once. - `response_format`: Sets the return format.

After the call, we find the return result as follows: ```json { "id": "chatcmpl-Cmd6uwSxN75F4PAdQSFEO8f2QPs4E", "object": "chat.completion", "created": 1765706120, "model": "gpt-5.5", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! What can I help you with today?", "refusal": null, "annotations": [] }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 7, "completion_tokens": 13, "total_tokens": 20, "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": null } ``` The return result contains multiple fields, described as follows: - `id`: The ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`: The selected OpenAI ChatGPT model. - `choices`: The response information provided by ChatGPT for the question. - `usage`: Statistics on token usage for this Q&A. Among them, `choices` contains the response information from ChatGPT, and within it, the `choices` is ChatGPT, as shown in the figure.

As can be seen, the `content` field in `choices` contains the specific content of ChatGPT's reply. ## Streaming Response This interface also supports streaming responses, which is very useful for web integration, allowing the webpage to achieve a word-by-word display effect. If you want to return responses in a streaming manner, you can change the `stream` parameter in the request header to `true`. Modify as shown in the figure, but the calling code needs to have corresponding changes to support streaming responses.

After changing `stream` to `true`, the API will return the corresponding JSON data line by line, and we need to make corresponding modifications at the code level to obtain the line-by-line results. Python sample calling code: ```python import requests url = "https://api.acedata.cloud/openai/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-4", "messages": [{"role":"user","content":"hello"}], "stream": True } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The output effect is as follows: ```json data: {"choices": [{"delta": {"role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": "Hi", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " there", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": "!", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " How", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " can", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " I", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " assist", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " you", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": " today", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"content": "?", "role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"role": "assistant"}, "index": 0}], "created": 1721007348, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: {"choices": [{"delta": {"role": "assistant"}, "finish_reason": "stop", "index": 0}], "created": 1721007349, "id": "chatcmpl-YzczYjVhNjhjMzMwNDQ5MDkyNGYzOGZjZGE1ZGQ5OGU", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all"} data: [DONE] ``` It can be seen that there are many `data` in the response, and the `choices` in `data` are the latest response content, consistent with the content introduced above. The `choices` are the newly added response content, which you can use to connect to your system. At the same time, the end of the streaming response is determined by the content of `data`. If the content is `[DONE]`, it indicates that the streaming response has completely ended. The returned `data` result has multiple fields, which are described as follows: - `id`, the ID generated for this dialogue task, used to uniquely identify this dialogue task. - `model`, the OpenAI ChatGPT model selected. - `choices`, the response information provided by ChatGPT to the prompt. JavaScript is also supported, for example, the streaming call code for Node.js is as follows: ```javascript const options = { method: "post", headers: { accept: "application/json", authorization: "Bearer {token}", "content-type": "application/json", }, body: JSON.stringify({ model: "gpt-4", messages: [{ role: "user", content: "hello" }], stream: true, }), }; fetch("https://api.acedata.cloud/openai/chat/completions", options) .then((response) => response.json()) .then((response) => console.log(response)) .catch((err) => console.error(err)); ``` Java sample code: ```java JSONObject jsonObject = new JSONObject(); jsonObject.put("model", "gpt-4"); jsonObject.put("messages", [{"role":"user","content":"hello"}]); jsonObject.put("stream", true); MediaType mediaType = "application/json; charset=utf-8".toMediaType(); RequestBody body = jsonObject.toString().toRequestBody(mediaType); Request request = new Request.Builder() .url("https://api.acedata.cloud/openai/chat/completions") .post(body) .addHeader("accept", "application/json") .addHeader("authorization", "Bearer {token}") .addHeader("content-type", "application/json") .build(); OkHttpClient client = new OkHttpClient(); Response response = client.newCall(request).execute(); System.out.print(response.body!!.string()) ``` Other languages can be rewritten accordingly; the principle is the same. ## Multi-turn Dialogue If you want to connect to the multi-turn dialogue feature, you need to upload multiple prompts in the `messages` field. The specific examples of multiple prompts are shown in the image below:

Python sample call code: ```python import requests url = "https://api.acedata.cloud/openai/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-4", "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi! How can I assist you today?"},{"role":"user","content":"What I say just now?"}] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` By uploading multiple question words, multi-turn dialogue can be easily achieved, resulting in the following response: ```json { "choices": [ { "index": 0, "message": { "role": "assistant", "content": "You said, \"Hello.\"" }, "finish_reason": "stop" } ], "created": 1721323012, "id": "chatcmpl-NWZmOTA5MDlkZjBjNDRjNGEwMzRjYzA5NmM1MzQwMWY", "model": "gpt-4", "object": "chat.completion.chunk", "recipient": "all", "usage": { "prompt_tokens": 31, "completion_tokens": 6, "total_tokens": 37 } } ``` As can be seen, the information contained in `choices` is consistent with the basic usage content, which includes the specific content of ChatGPT's responses to multiple dialogues, allowing for answers to corresponding questions based on multiple dialogue contents. ## Integrating OpenAI-Python The OpenAI Chat Completion API is compatible with the official OpenAI interface and can be directly integrated using the official SDK [OpenAI-Python](https://github.com/openai/openai-python). This article will briefly introduce the usage. 1. First, set up a local `Python` environment, which can be searched on Google. 2. Download and install a development environment, such as the VSCode editor. 3. Configure the `OpenAI` environment variables. - In the project folder, create a file named `.env` and save it. - The content of the `.env` file: ```json OPENAI_API_KEY="sk-xxx" OPENAI_BASE_URL="https://api.acedata.cloud/openai" # Reminder: If you are using the official OpenAI key, do not use this address. ``` Replace `sk-xxx` with your own key. `OPENAI_BASE_URL` is the proxy interface for accessing OpenAI. 4. Install the project's dependency packages. ```shell pip install openai ``` The command for Mac OS is: ```shell pip3 install openai ``` 5. Create a sample source code file. Assuming we create a sample code `index.py`, the specific content is as follows: ```python import os from openai import OpenAI client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY")) response = client.chat.completions.create( messages=[ { "role": "user", "content": "hello", } ], model="gpt-4", ) print(response.text) ``` ## Online Model The gpt-3.5-browsing and gpt-4-browsing models are different from other models; they can perform online searches based on the question words and return the results of the online search with appropriate adjustments. This article will demonstrate the online functionality through a specific example, and you can fill in the corresponding content on the OpenAI Chat Completion API interface, as shown in the figure:

You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing.

After the call, we find that the returned result is as follows: ```json { "choices": [ { "index": 0, "message": { "role": "assistant", "content": "For the latest news in China today, you can check major news websites such as:\n\n- [BBC News China](https://www.bbc.com/news/world/asia/china)\n- [CNN China News](https://edition.cnn.com/china)\n- [Reuters China](https://www.reuters.com/news/archive/china-news)\n\nThese sources will have up-to-date information on current events in China." }, "finish_reason": "stop" } ], "created": 1721009347, "id": "chatcmpl-YzA0M2RjZDVkYThlNDkxNTkzOThmZWQ4OGMzNzdhNzA", "model": "gpt-4-browsing", "object": "chat.completion.chunk", "recipient": "all", "usage": { "prompt_tokens": 325, "completion_tokens": 82, "total_tokens": 407 } } ``` As can be seen, the response information in `choices` is obtained based on online queries and also provides relevant links. The response information in `choices` needs to be rendered using `markdown` syntax to achieve the best experience, which ultimately reflects the powerful advantages of our model's online functionality. ## Visual Model gpt-4o is a multimodal large language model developed by OpenAI, which adds visual understanding capabilities on the basis of GPT-4. This model can process both text and image inputs simultaneously, achieving cross-modal understanding and generation. The text processing using the gpt-4o model is consistent with the basic usage content mentioned above. Below, we will briefly introduce how to use the model's image processing capabilities. The image processing capability of the gpt-4o model is mainly achieved by adding a `type` field to the original `content`, which indicates whether the uploaded content is text or an image, thus utilizing the image processing capabilities of the gpt-4o model. Below, we will mainly discuss how to call this function using both Curl and Python. - Curl script method ``` curl -X POST 'https://api.acedata.cloud/openai/chat/completions' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "model": "gpt-4o", "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" } } ] } ] }' ``` - Python script method ```python import requests url = "https://api.acedata.cloud/openai/chat/completions" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-4o", "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" } }, ], } ] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Then you can get the following result, where the field information is consistent with the above text, specifically as follows: ```json { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-4-vision-preview", "system_fingerprint": "fp_44709d6fcb", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "\n\n这张图片展示了一条木栈道延伸穿过郁郁葱葱的沼泽地。" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } } ``` It can be seen that the content of the answer is based on the image, so through the above two methods, the text and image processing capabilities of the gpt-4-vision model can be easily utilized. In addition to gpt-4o, there is a lower-cost model called gpt-4o-mini. gpt-4o-mini is the latest generation of large language models developed by OpenAI, which not only responds quickly but is also cheaper and supports multimodal capabilities. The use of vision features can refer to the content of the gpt-4o model mentioned above. ## GPT-4o Drawing Model ### Generate Images Based on Reference Images Below is an example of generating a custom style image based on a picture. First, let’s take a look at the input image, as shown below: ![](https://cdn.acedata.cloud/qzx2z1.png) It can be seen that the reference image is a real person's picture. We can ask it to change to a certain style, for example, to turn it into an anime-style image, with the specific request example: ```json { "model": "gpt-4o-image", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "生成动漫风格的图片，并且带上个帽子" }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/qzx2z1.png" } } ] } ], "stream": false } ``` Sample result: ```json { "id": "chatcmpl-89DPQxbLuyRNzH5YLCPYM5WElV3dm", "object": "chat.completion", "created": 1781020664, "model": "gpt-4o-image", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "\n\n> 🎨 生成中...\n\n![https://platform.cdn.acedata.cloud/20260609/0f7b6cf1b14843b1bab8e261fe5765b3.png](https://platform.cdn.acedata.cloud/20260609/0f7b6cf1b14843b1bab8e261fe5765b3.png)\n\n[点击下载](https://platform.cdn.acedata.cloud/download/20260609/0f7b6cf1b14843b1bab8e261fe5765b3.png)" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 100, "completion_tokens": 122, "total_tokens": 222, "prompt_tokens_details": { "text_tokens": 93, "cached_tokens_details": {} }, "completion_tokens_details": {} } } ``` Among them, the `choices` in the `message.content` is the complete dialogue result generated, and the image is included in Markdown format (the image link is a temporary address, please download and save it in time). It can be seen that the generated image is indeed in anime style, as shown in the following image:

### Pure Text Image Generation We can generate an image through a prompt and return it to us in a conversational result. Below, we take `create an image of a futuristic city at sunset` as an example, with the specific example as follows: ```json { "model": "gpt-4o-image", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "创建一张未来城市日落的图片" } ] } ], "stream": false } ``` Sample result: ```json { "id": "chatcmpl-89DqkpQoPGkQqJ6kPKMKWejjLXVxQ", "object": "chat.completion", "created": 1781020587, "model": "gpt-4o-image", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "\n\n> 🎨 生成中...\n\n![https://platform.cdn.acedata.cloud/20260609/ed2cca68732540fc99162ddc10ddc153.png](https://platform.cdn.acedata.cloud/20260609/ed2cca68732540fc99162ddc10ddc153.png)\n\n[点击下载](https://platform.cdn.acedata.cloud/download/20260609/ed2cca68732540fc99162ddc10ddc153.png)" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 17, "completion_tokens": 104, "total_tokens": 121, "prompt_tokens_details": { "text_tokens": 10, "cached_tokens_details": {} }, "completion_tokens_details": {} } } ``` It can be seen that the result is consistent with the prompt, as shown below:

### Generate One Image from Multiple Images We can also use multiple reference images to generate one image. For example, using a handsome guy and a coffee image, these two images can be used to generate an image of a handsome guy drinking coffee. Below are the specific reference images:

Next, we take `generate an image of a boy holding coffee and about to drink` as an example, with the specific example as follows: ```json { "model": "gpt-4o-image", "messages": [ { "role": "user", "content": [ { "type": "text", "text": "Generate an image of a boy holding coffee and about to drink it." }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/pqquv3.jpg" } }, { "type": "image_url", "image_url": { "url": "https://cdn.acedata.cloud/h8j2i0.jpg" } } ] } ], "stream": false } ``` Sample result: ```json { "id": "chatcmpl-89DnHbbzOIQvU1VzJrNjzMU8BRUgG", "object": "chat.completion", "created": 1781021018, "model": "gpt-4o-image", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "\n\n> 🎨 Generating...\n\n![https://platform.cdn.acedata.cloud/20260610/f1d9ddee3c304230a9f92929f04b95be.png](https://platform.cdn.acedata.cloud/20260610/f1d9ddee3c304230a9f92929f04b95be.png)\n\n[Click to download](https://platform.cdn.acedata.cloud/download/20260610/f1d9ddee3c304230a9f92929f04b95be.png)" }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 193, "completion_tokens": 116, "total_tokens": 309, "prompt_tokens_details": { "text_tokens": 186, "cached_tokens_details": {} }, "completion_tokens_details": {} } } ``` As you can see, the generated result indeed combines the two images to create the output, here is the specific result:

## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ``` { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to easily implement the conversational features of the official OpenAI ChatGPT using the OpenAI Chat Completion API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Producer Audios Generation API Integration Instructions This document will introduce the integration instructions for the Producer Audios Generation API, which can generate official music from Producer by inputting custom parameters. ## Application Process To use Producer Audios Generation API, first open the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) and copy your API Token. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in, you will be redirected to sign in and brought back to this page automatically. **A single API Token works across every service on the platform — no need to subscribe per service.** New accounts receive free starter credit; when it runs low you can top up your shared balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Full documentation: [Producer Audios Generation API →](https://platform.acedata.cloud/documents/producer-audios) ## Basic Usage You can input any text to generate songs. For example, if I want to generate a song about Christmas, I can input `a song for Christmas`, as shown in the image:

Here, we have set the Request Headers, including: - `accept`: the format of the response you want to receive, filled in as `application/json`, which means JSON format. - `authorization`: the key to call the API, which can be selected directly after application. Additionally, the parameters in the Request Body include: - `action`: the action for this music generation task, which is `generate` for generating a song. - `model`: the model used to create the song, currently mainly including: **FUZZ-2.0 Pro**, **FUZZ-2.0**, **FUZZ-2.0 Raw**, **FUZZ-1.1 Pro**, **FUZZ-1.0 Pro**, **FUZZ-1.0**, **FUZZ-1.1**, **FUZZ-0.8**. - `lyric`: the content of the song lyrics. - `custom`: whether to generate the song in a custom way. - `prompt`: the prompt words in inspiration mode. - `title`: the title information of the song. - `audio_id`: the reference song ID for continuation/revision operations. - `continue_at`: to continue writing the song from a specified second. - `replace_section_start`/`replace_section_end`: the start and end time for replacing sections, in seconds. - `lyrics_strength`: the strength of the lyrics, indicating the degree of influence of the lyrics in audio generation, optional between 0-1, default is 0.7. - `sound_strength`: the strength of the audio prompt, optional between 0.2-1, default is 0.7. - `cover_strength`: the cover strength between 0.2-1, default is 1. - `weirdness`: the style peculiarity, optional between 0-1, default is 0.5. - `callback_url`: the URL to receive callback results. - `instrumental`: whether it is a no-lyric mode. After selection, you can see that the corresponding code is generated on the right side, as shown in the image:

Click the "Try" button to test, as shown in the image above, and we get the following result: ```json { "success": true, "task_id": "82fd443a-903a-4f18-8028-12d2f8a0a4be", "trace_id": "d85839fa-0bb1-42da-a9fc-cd582c29027d", "data": [ { "id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d", "title": "Untitled", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/image/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.jpg", "lyric": "[Instrumental]", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/a853673e-615c-42ae-bdff-16b1add94861/audio/6c947f13-a3c5-4b9c-8609-5639c37cdc2d.m4a", "video_url": null, "image_id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d", "topic": null, "seed": "2450882164", "sound": "A song for Christmas", "created_at": "2025-12-30T17:18:23.232911Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "181.3014058956916" } ] } ``` The returned result contains multiple fields, described as follows: - `success`, the status of the music generation task at this time. - `data`, the result of this music task - `id`, the ID of the music generation task at this time. - `sound`, the prompt words for the music generation task at this time. - `seed`, the seed value for the music generation task at this time. - `audio_url`, the audio link for the music generation task at this time. - `image_url`, the cover link for the music generation task at this time. - `image_id`, the cover ID for the music generation task at this time. - `state`, the status of the music generation task at this time. - `duration`, the duration information of the music at this time. - `progress`, the progress value of the music task at this time. - `model`, the model information used for the music generation task at this time. - `lyric`, the lyrics information for the music generation task at this time. We can see that we have obtained the music information we want to generate, and we only need to obtain the generated Producer music from the music link address in the `data` result. Additionally, if you want to generate the corresponding integration code, you can directly copy the generated code, for example, the CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "FUZZ-2.0 Pro", "prompt": "A song for Christmas" }' ``` ## Custom Generation If you want to customize the lyrics, you can input the lyrics: At this time, the `lyric` field can accept content similar to the following: ``` [Verse]Woke up with the sun in my eyesNo clouds above just blue in the skiesShoes on my feet I’m ready to runEvery step feels like a loaded gun[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Verse 2]Dancing through the city streetsA rhythm pounding in my heartbeatStrangers smile it’s catching onThis world’s a stage we’re all a song[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Bridge]Throw your worries out the doorLet them sink to the ocean floorWe’re alive and it’s enoughLife is messy but it’s love[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high ``` Next, we need to customize the song generation based on the lyrics, title, and style, specifying the following content: - lyric: the lyrics text - custom: set to `true`, indicating custom generation; this parameter defaults to false, indicating the use of `prompt` for generation. - title: the title of the song. Fill in the example as follows:

After filling it out, the generated code is as follows:

Corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "FUZZ-2.0 Pro", "instrumental": false, "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "custom": true }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "9f58bbd4-855a-4233-ac45-b63bf9168e02", "trace_id": "145ad117-6ce7-42dd-af12-70751c5284fc", "data": [ { "id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32", "title": "Woke up with the sun in my eyes", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/38d3b9e2-0dfb-4338-b2a7-15e45656ed32.m4a", "video_url": null, "image_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32", "topic": null, "seed": "3789209121", "sound": "", "created_at": "2025-12-30T17:26:46.357055Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "153.80897959183673" } ] } ``` ## Cover Songs If you want to perform a cover operation on an already generated song, you can input the song generated above for the cover, and next we will customize the song generation based on the lyrics and title. If you want to continue covering a song you uploaded, you can set the parameter `action` to `upload_cover` and input the ID of the song you need to continue covering. The song ID can be obtained using the [Producer Upload API](https://platform.acedata.cloud/documents/producer-upload), as shown in the image below:

You can specify the following content: - action: The action for this song task, currently supports: generate, cover, extend, upload_cover, upload_extend, replace_section, swap_vocals, swap_instrumentals, variation, this cover uses the `cover` parameter. - lyric: Lyric text - title: The title of the song. - custom: Whether to use custom mode for generation, default is false. - audio_id: The ID of the song to be covered. Fill in the example as follows:

After filling it out, the generated code is as follows:

Corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "cover", "model": "FUZZ-2.0 Pro", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32", "instrumental": false, "custom": true, "title": "Cover" }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "dbca350e-6fb9-46ca-9c7e-4c1a9080806f", "trace_id": "a39e0fff-ced8-4b31-ae23-aef3badd90fa", "data": [ { "id": "e52dd729-38b4-4c2f-9031-59eb7953c593", "title": "Cover", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/e52dd729-38b4-4c2f-9031-59eb7953c593.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/e52dd729-38b4-4c2f-9031-59eb7953c593.m4a", "video_url": null, "image_id": "e52dd729-38b4-4c2f-9031-59eb7953c593", "topic": null, "seed": "358803418", "sound": "", "created_at": "2025-12-30T17:32:32.951948Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "153.0659410430839" } ] } ``` ## Continue Writing the Song If you want to continue writing the song, we need to pass the `action` parameter value as: `extend`, and then we need to customize the song generation based on the lyrics, title, and style. If you want to continue writing a song that you uploaded, you can set the `action` parameter to `upload_extend` and input the ID of the song you want to continue writing. The song ID can be obtained using the [Producer Upload API](https://platform.acedata.cloud/documents/producer-upload), as shown in the image below:

The sample input is as follows:

After filling it out, the code is automatically generated as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "extend", "model": "FUZZ-2.0 Pro", "instrumental": false, "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "continue_at": 3, "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32", "custom": true, "title": "Extend", "weirdness": 0.3, "sound_strength": 0.3, "lyrics_strength": 0.6 }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "834983cb-d62d-4750-b1aa-461da137e51f", "trace_id": "6923eee2-7403-432c-8bd1-e471086385b0", "data": [ { "id": "d9ebc609-fb65-4a23-b914-c074747af6a4", "title": "Extend", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/d9ebc609-fb65-4a23-b914-c074747af6a4.jpg", "lyric": "[Verse]\n[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/d9ebc609-fb65-4a23-b914-c074747af6a4.m4a", "video_url": null, "image_id": "d9ebc609-fb65-4a23-b914-c074747af6a4", "topic": null, "seed": "4294469624", "sound": "", "created_at": "2025-12-30T17:36:14.520928Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "173.87102040816328" } ] } ``` ## Music Variation If you want to generate a new piece of music with a similar effect based on the seed value of the previous music, we need to pass the `action` parameter value as: `variation`, and then we can customize the generation of a new piece of music with a similar effect. The sample input is as follows:

After filling out, the code is automatically generated as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "variation", "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4", "model": "FUZZ-2.0 Pro", "instrumental": false, "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "custom": true }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "3a74da6d-a37d-4b5d-b116-821f455bce39", "trace_id": "8e28cce0-0400-4bfd-83db-6d27f97422c7", "data": [ { "id": "c14ca458-cd5a-4700-83d4-5249e15f2707", "title": "Woke up with the sun in my eyes", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/c14ca458-cd5a-4700-83d4-5249e15f2707.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/c14ca458-cd5a-4700-83d4-5249e15f2707.m4a", "video_url": null, "image_id": "c14ca458-cd5a-4700-83d4-5249e15f2707", "topic": null, "seed": "2082104582", "sound": "", "created_at": "2025-12-30T17:48:40.135187Z", "model": "FUZZ-2.0", "progress": "100%", "state": "succeeded", "duration": "173.12798185941043" } ] } ``` ## Replace Section If you want to replace a section of the song, we need to pass the `action` parameter value as: `replace_section`, and then we need to customize the song generation based on the lyrics and title. If you want to continue replacing a section of a song you uploaded, you can set the `action` parameter to `upload_replace_section` and input the ID of the song you need to continue writing. The song ID can be obtained using the [Producer Upload API](https://platform.acedata.cloud/documents/producer-upload), as shown in the image below:

An example of filling out is as follows:

After filling out, the code is automatically generated as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "replace_section", "model": "FUZZ-2.0 Pro", "instrumental": false, "lyric": "[Verse]\\nWoke up with the sun in my eyes\\nNo clouds above just blue in the skies\\nShoes on my feet I’m ready to run\\nEvery step feels like a loaded gun\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Verse 2]\\nDancing through the city streets\\nA rhythm pounding in my heartbeat\\nStrangers smile it’s catching on\\nThis world’s a stage we’re all a song\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Bridge]\\nThrow your worries out the door\\nLet them sink to the ocean floor\\nWe’re alive and it’s enough\\nLife is messy but it’s love\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high", "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4", "replace_section_start": 3, "replace_section_end": 70, "custom": true }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "3cb5ae96-01b0-4a37-afb0-e582608af56f", "trace_id": "3ebc6f63-5093-4499-bf9b-95c239e0da4f", "data": [ { "id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f", "title": "Woke up with the sun in my eyes", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/a54609c6-13e2-4176-be0f-4d7eebc68e1f.jpg", "lyric": "[Verse]\\nWoke up with the sun in my eyes\\nNo clouds above just blue in the skies\\nShoes on my feet I’m ready to run\\nEvery step feels like a loaded gun\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Verse 2]\\nDancing through the city streets\\nA rhythm pounding in my heartbeat\\nStrangers smile it’s catching on\\nThis world’s a stage we’re all a song\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Bridge]\\nThrow your worries out the door\\nLet them sink to the ocean floor\\nWe’re alive and it’s enough\\nLife is messy but it’s love\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/a54609c6-13e2-4176-be0f-4d7eebc68e1f.m4a", "video_url": null, "image_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f", "topic": null, "seed": "14887454", "sound": "", "created_at": "2025-12-30T18:01:19.907443Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "174.6140589569161" } ] } ``` ## Accompaniment Remix If you want to use the official accompaniment remix operation, you can set the `action` parameter value to: `swap_instrumentals`, then we will customize the song generation based on the lyrics and title. The example to fill in is as follows:

After filling it out, the generated code is as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "swap_instrumentals", "model": "FUZZ-2.0 Pro", "weirdness": 0.6, "prompt": "Happy", "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4" }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "d17d8376-3a58-451d-a976-404719bac11d", "trace_id": "ab596807-910a-4e30-bae2-4647895f7d0b", "data": [ { "id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b", "title": "Extend (Sound swap)", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b.m4a", "video_url": null, "image_id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b", "topic": null, "seed": "2157878068", "sound": "Happy", "created_at": "2025-12-30T18:09:49.594800Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "172.3849433106576" } ] } ``` ## Vocal Remix If you want to use the official vocal remix operation, you can set the `action` parameter value to: `swap_vocals`, then we will customize the song generation based on the lyrics, title, and style. The example to fill in is as follows:

After filling it out, the generated code is as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "swap_vocals", "model": "FUZZ-2.0 Pro", "instrumental": false, "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "weirdness": 0.6, "lyrics_strength": 0.8, "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4", "custom": true }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "a903ac38-f129-4f85-9181-b1dc5579bd32", "trace_id": "9953af52-45e0-4808-bf13-88f0b21262c1", "data": [ { "id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b", "title": "Woke up with the sun in my eyes", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/image/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/7ce2b11a-179f-4b87-b5ff-397613c62c93/audio/7b2d653b-aaaa-41b0-b737-aee4c4c5693b.m4a", "video_url": null, "image_id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b", "topic": null, "seed": "2484735707", "sound": "", "created_at": "2025-12-30T18:13:01.349875Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "173.12798185941043" } ] } ``` ## Lyrics and Music Separation If you want to use the official lyrics and music separation operation, you can set the `action` parameter value to: `stems`, and then we need to perform lyrics and music separation based on the song ID. The sample input is as follows:

After filling it out, the generated code is as follows:

The corresponding code: ```shell curl -X POST 'https://api.acedata.cloud/producer/audios' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "stems", "audio_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f" }' ``` Testing is allowed, and the generated effect is similar. ```json { "success": true, "task_id": "561ac695-b4aa-47cf-978d-fb7be2b9ebfc", "trace_id": "66d0d397-2987-4bde-84fb-a60d0023b217", "data": [ { "title": "Woke up with the sun in my eyes", "lyric": "", "stems_url": "https://platform.cdn.acedata.cloud/producer/561ac695-b4aa-47cf-978d-fb7be2b9ebfc.zip", "model": "", "progress": "100%", "state": "succeeded" } ] } ``` ## Asynchronous Callback Since the Producer Audios Generation API can take a relatively long time to generate, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the result of the generated task will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let’s understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, we use a public Webhook sample site [https://webhook.site/](https://webhook.site/). Opening this site will give you a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/tbcnai.png) Copy this URL, and it can be used as a Webhook. The sample here is [https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1](https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1). Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the image:

Clicking run, you can find that you will immediately receive a result, as follows: ``` { "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad" } ``` Please wait a moment, we can observe the results of the generated task at [https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1](https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1), as shown in the image below: ![](https://cdn.acedata.cloud/k0kf0y.png) The content is as follows: ```json { "success": true, "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad", "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb", "data": [ { "id": "1dd08826-478e-43a6-868f-aff5ababac2c", "title": "Woke up with the sun in my eyes", "image_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/image/1dd08826-478e-43a6-868f-aff5ababac2c.jpg", "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high", "audio_url": "https://storage.googleapis.com/corpusant-app-public/riffs/3bff6223-fe13-4bef-973e-2cbaef430d5d/audio/1dd08826-478e-43a6-868f-aff5ababac2c.m4a", "video_url": null, "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c", "topic": null, "seed": "1490770667", "sound": "", "created_at": "2025-12-30T18:36:00.994141Z", "model": "FUZZ-2.0 Pro", "progress": "100%", "state": "succeeded", "duration": "135.2330158730159" } ] } ``` We can see that the result contains a `task_id` field, and other fields are similar to the above text. This field can be used to associate tasks. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Producer Audios Generation API to generate music by inputting prompts. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Veo Videos Generation API Integration Instructions This article will introduce the integration instructions for the Veo Videos Generation API, which can generate official Veo videos by inputting custom parameters. ## Application Process To use the Veo Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Veo Videos Generation API →](https://platform.acedata.cloud/documents/veo-videos) ## Basic Usage First, understand the basic usage method, which involves inputting the prompt `prompt`, the generation action `action`, an array of reference images for the first and last frames `image_urls`, and the model `model` to obtain the processed result. You first need to simply pass a field `action`, with the value `text2video`, which mainly includes three actions: text to video (`text2video`), image to video (`image2video`), and get 1080p video (`get1080p`). Then, we also need to input the model `model`, which currently mainly includes `veo31-fast`, `veo3`, `veo31`, `veo3-fast`, and `veo31-fast-ingredients`, with specific content as follows:

Here we can see that we have set the Request Headers, including: - `accept`: the format of the response result you want to receive, filled in as `application/json`, which is JSON format. - `authorization`: the key to call the API, which can be directly selected after application. Additionally, we set the Request Body, including: - `model`: the model for generating the video, mainly including `veo31-fast`, `veo3`, `veo31`, `veo3-fast`, and `veo31-fast-ingredients`. - `action`: the action for this video generation task, mainly including three actions: text to video (`text2video`), image to video (`image2video`), and get 1080p video (`get1080p`). - `image_urls`: when selecting the image to video action `image2video`, it is necessary to upload the reference image links. `veo31-fast-ingredients` allows up to 3 images (multi-image fusion), while other models allow up to 2 images (first and last frame mode). - `resolution`: choose the resolution of the generated video, where the veo31 model supports 4k resolution, while other models do not. All models support 1080p and gif resolutions; if this value is not provided, the default is 720p resolution, mainly divided into: `1080p`, `gif`, `4k`. - `prompt`: the prompt. - `callback_url`: the URL to receive the callback result. - `async`: optional, when set to `true`, the interface immediately returns `task_id`, and there is no need to provide `callback_url`, then the result can be polled through the corresponding task query interface. ### 📌 Model Summary | **Model Name** | **Supported Modes** | **Image Input Rules** | | -------------------------- | --------------------------------- | --------------------------------- | | **veo3-fast** | Text to video (no image)
Image to video mode (with image) | **1 image** → First frame mode
**2 images** → First and last frame mode | | **veo31-fast** | Text to video (no image)
Image to video mode (with image) | **1 image** → First frame mode
**2 images** → First and last frame mode | | **veo31-fast-ingredients** | ❌ Text to video (not supported)
✅ **Mandatory multi-image fusion** (must provide images) | **1-3 images** → Multi-image fusion mode (up to 3 images) | | **veo3** | Text to video (no image)
Image to video mode (with image) | **1 image** → First frame mode
**2 images** → First and last frame mode | | **veo31** | Text to video (no image)
Image to video mode (with image) | **1 image** → First frame mode
**2 images** → First and last frame mode | --- ### 🔑 Key Rules Explanation 1. **General Logic**: - **No image input** → Automatically triggers text to video mode. - **With image input** → Triggers image to video mode (specific behavior determined by the number of images). 2. **Image to Video Mode Types**: - **First frame mode** (1 image): The first frame is fixed as the input image. - **First and last frame mode** (2 images): The first and last frames are fixed as the input images. - **Multi-image fusion mode** (1-3 images): Only supported by `veo31-fast-ingredients`, fuses multiple images to generate a video. 3. **Mode Classification**: - **Fast Mode**: `veo3-fast`, `veo31-fast`, `veo31-fast-ingredients`. - **Quality Mode**: `veo3`, `veo31` (higher generation quality). --- ### ⚠️ Notes - **The only model that requires image input**: `veo31-fast-ingredients` must provide images (1-3 images), otherwise it cannot run. - **Image Quantity Limit**: - `veo31-fast-ingredients` supports **1-3 images** input (multi-image fusion mode). - Other models support a maximum of **2 images** input (first and last frame mode). After selection, you can see that the corresponding code is also generated on the right side, as shown in the image:

Click the "Try" button to test, as shown in the image above, and we obtained the following result: ```json { "success": true, "task_id": "697ea2fc-58fd-48c8-8191-29041ff23c3c", "trace_id": "70e1cb12-c619-4292-a416-90191205996b", "data": [ { "id": "24ac06a5-9cc7-448f-802e-0b4db19f6e96", "video_url": "https://platform2.cdn.acedata.cloud/veo/f5389ec0-2eb5-4212-b4a8-04b513b0129a.mp4", "created_at": "2026-06-30T04:01:50.364Z", "complete_at": "2026-06-30T04:03:20.495Z", "state": "succeeded" } ] } ``` The returned result contains multiple fields, described as follows: - `success`, the status of the video generation task at this time. - `task_id`, the ID of the video generation task at this time. - `data`, the result of the video generation task at this time. - `id`, the video ID of the video generation task at this time. - `video_url`, the video link of the video generation task at this time. - `created_at`, the creation time of the video generation task at this time. - `complete_at`, the completion time of the video generation task at this time. - `state`, the status of the video generation task at this time. We can see that we have obtained satisfactory video information, and we only need to obtain the generated Veo video based on the video link address in the `data` result. Additionally, if you want to generate the corresponding integration code, you can directly copy the generated code, for example, the CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/veo/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "veo31-fast", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }' ``` ## Image to Video Function If you want to generate a video based on the first and last frame images, you can set the parameter `action` to `image2video`, and input the array of first and last frame image links `image_urls`. Next, we must fill in the prompt words needed for the next step to customize the generated video, specifying the following content: - `model`: the model for generating the video, mainly `veo31-fast`, `veo3`, `veo31`, `veo3-fast`, and `veo31-fast-ingredients`. - `image_urls`: when selecting the image to video action `image2video`, you must upload the reference image links. - `prompt`: prompt words. An example of filling in is as follows:

After filling in, the code is automatically generated as follows:

The corresponding Python code: ```python import requests url = "https://api.acedata.cloud/veo/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "image2video", "model": "veo31-fast", "prompt": "Let it dance", "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"] } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Clicking run, you can find that a result is obtained, as follows: ```json { "success": true, "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87", "trace_id": "8bc68066-36de-41ef-ae5e-b7d61ff6aee8", "data": [ { "id": "59f12222b1fa4fbe9331ff2400ad1583", "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4", "created_at": "2025-07-25 16:13:07", "complete_at": "2025-07-25 16:16:12", "state": "succeeded" } ] } ``` It can be seen that the result content is consistent with the above text, thus achieving the image to video function. ## Get 1080p Video Function If you want to get 1080p for an already generated Veo video, you can set the parameter `action` to `get1080p`, and input the ID of the video you need to get 1080p for. The video ID can be obtained based on basic usage, as shown in the following image:

At this time, you can see that the video ID is: ```json "id": "59f12222b1fa4fbe9331ff2400ad1583" ``` > Note that the `video_id` here is the ID of the generated video. If you do not know how to generate a video, you can refer to the basic usage above to generate a video. Next, we must fill in the prompt words needed for the next step to customize the generated video, specifying the following content: - `model`: the model for generating the video, mainly `veo31-fast`, `veo3`, `veo31`, `veo3-fast`, and `veo31-fast-ingredients`. - `video_id`: the reference video ID used to get the 1080p video. An example of filling in is as follows:

After filling in, the code is automatically generated as follows:

Clicking run, you can find that a result is obtained, as follows: ```json { "success": true, "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984", "trace_id": "a8922eec-6f50-4f77-8104-00ded071d59d", "data": [ { "id": "59f12222b1fa4fbe9331ff2400ad1583", "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4", "created_at": "2025-07-25 16:13:07", "complete_at": "2025-07-25 16:16:12", "state": "succeeded" } ] } ``` It can be seen that the result content is consistent with the above text, thus achieving the function of obtaining the 1080p video. ## Specify Video Size Generation If you want to specify the generation of a custom-sized Veo video, you can set the parameter `aspect_ratio` to the desired size. Next, we must fill in the prompt words needed for the next step to customize the generated video, specifying the following content: - `model`: the model for generating the video, mainly `veo31-fast`, `veo3`, `veo31`, `veo3-fast`, and `veo31-fast-ingredients`. - `aspect_ratio`: the size of the video, currently supporting: `16:9`, `16:9`, `3:4`, `4:3`, `1:1`, with the default being `16:9`. - `translation`: whether to enable automatic translation of prompt words, default is `false`. An example of filling in is as follows:

After filling in, the code is automatically generated as follows:

Clicking run, you can find that a result is obtained, as follows: ```json { "success": true, "task_id": "d2b93290-ab0e-4d20-ae45-60c062a32687", "trace_id": "9834e64d-c8fe-43ae-8114-ee2b5f93d886", "data": [ { "id": "fc667e7d3b8f44beaa61a3c339af0e50", "video_url": "https://platform.cdn.acedata.cloud/veo/d2b93290-ab0e-4d20-ae45-60c062a32687.mp4", "created_at": "2025-08-24 20:09:06", "complete_at": "2025-08-24 20:10:45", "state": "succeeded" } ] } ``` It can be seen that the result content is consistent with the above text, which also achieves the function of generating videos of specified dimensions. ## Asynchronous Callback Since the time taken by the Veo Videos Generation API is relatively long, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field, representing the current task ID. When the task is completed, the result of the generated video will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let's understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, a public Webhook sample site https://webhook.site/ is used. By opening this site, you can obtain a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/tbcnai.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc`. Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the image:

Clicking run, you can find that an immediate result is obtained, as follows: ```json { "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed" } ``` After a moment, we can observe the result of the generated video at `https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc`, as shown in the image: ![](https://cdn.acedata.cloud/238i32.png) The content is as follows: ```json { "success": true, "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "data": [ { "id": "2f43ceed37944b4d836e1a1899dad0a1", "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4", "created_at": "2025-07-25 17:19:20", "complete_at": "2025-07-25 17:21:45", "state": "succeeded" } ] } ``` It can be seen that the result contains a `task_id` field, and the other fields are similar to the above text, allowing the task to be associated through this field. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Veo Videos Generation API to generate videos by inputting prompt words and reference images of the first frame. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. --- # Wan Videos Generation API Integration Instructions This article will introduce the Wan Videos Generation API integration instructions, which can generate official videos of Tongyi Wanxiang by inputting custom parameters. ## Application Process To use Wan Videos Generation API, first open the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) and copy your API Token. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in, you will be redirected to sign in and brought back to this page automatically. **A single API Token works across every service on the platform — no need to subscribe per service.** New accounts receive free starter credit; when it runs low you can top up your shared balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Full documentation: [Wan Videos Generation API →](https://platform.acedata.cloud/documents/wan-videos) ## Basic Usage First, understand the basic usage method, which involves inputting the prompt `prompt`, the action `action`, the first frame reference image `image_url`, and the model `model` to obtain the processed result. You first need to simply pass a field `action`, with the value set to `text2video`. It mainly includes two types of actions: text-to-video (`text2video`) and image-to-video (`image2video`). Then, we also need to input the model `model`, which currently mainly includes `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, and `wan2.6-t2v`. The specific content is as follows:

Here we can see that we have set the Request Headers, including: - `accept`: the format of the response result you want to receive, filled in as `application/json`, which means JSON format. - `authorization`: the key to call the API, which can be directly selected after application. Additionally, we set the Request Body, including: - `model`: the model for generating the video, mainly including `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, and `wan2.6-t2v`. - `action`: the action for this video generation task, mainly including three actions: text-to-video (`text2video`), image-to-video (`image2video`). When it is text-to-video, currently only the model `wan2.6-t2v` is supported. When it is image-to-video, currently only the models `wan2.6-i2v`, `wan2.6-r2v`, and `wan2.6-i2v-flash` are supported. - `image_url`: when selecting the image-to-video action `image2video`, it is necessary to upload the first frame reference image link. Currently, only the models `wan2.6-i2v` and `wan2.6-i2v-flash` are supported. - `reference_video_urls`: optional for image-to-video, specifies the reference video links for generation. Currently, only the model `wan2.6-r2v` is supported. - `size`: specifies the resolution of the generated video, in the format of width*height. The default value and available enumerated values for this parameter depend on the model parameter. For specific rules, please refer to the [official documentation](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model&url=2865250). - `duration`: the duration of the video generation, mainly supporting 5, 10, 15. - `shot_type`: optional, specifies the type of shot for the generated video, i.e., whether the video consists of a continuous shot or multiple switching shots. Effective condition: only effective when "prompt_extend": true. Parameter priority: shot_type > prompt. For example, if shot_type is set to "single", even if the prompt contains "generate multi-shot video", the model will still output a single-shot video. For specific rules, please refer to the [official documentation](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model&url=2865250). - `negative_prompt`: optional, reverse prompt words used to describe content that you do not want to see in the video frame, which can limit the video frame. Supports both Chinese and English, with a length not exceeding 500 characters; excess parts will be automatically truncated. Example values: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions, etc. - `resolution`: specifies the resolution level of the generated video, used to adjust the clarity of the video (total pixels). The model will automatically scale to a similar total pixel count based on the selected resolution level, and the video aspect ratio will try to maintain consistency with the aspect ratio of the input image img_url. For more details, please refer to the [official documentation](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model&url=2867393). - `audio_url`: the URL of the audio file, which the model will use to generate the video. For usage, refer to the [official documentation](https://modelstudio.console.alibabacloud.com/ap-southeast-1/?tab=api#/api/?type=model&url=2867393). - `audio`: whether to generate a video with sound. Parameter priority: audio > audio_url. When audio=false, even if audio_url is passed in, the output will still be a silent video, and billing will be calculated as a silent video. The default value is true. - `prompt_extend`: whether to enable intelligent rewriting of the prompt. When enabled, a large model will intelligently rewrite the input prompt. The effect of generation is significantly improved for shorter prompts, but it will increase processing time. The default value is true. - `prompt`: prompt words. - `callback_url`: the URL to which the results need to be returned. After selection, you can see that the corresponding code is also generated on the right side, as shown in the image:

Click the "Try" button to test, as shown in the image above, and we obtained the following result: ```json { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } ``` The returned result contains multiple fields, described as follows: - `success`: the status of the video generation task at this time. - `task_id`: the ID of the video generation task at this time. - `video_url`: the video link of the video generation task at this time. - `state`: the status of the video generation task at this time. We can see that we have obtained satisfactory video information, and we only need to obtain the generated Tongyi Wanxiang video based on the video link address in `video_url`. Additionally, if you want to generate the corresponding integration code, you can directly copy it, for example, the CURL code is as follows: ```shell curl -X POST 'https://api.acedata.cloud/wan/videos' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "text2video", "model": "wan2.6-t2v", "prompt": "Astronauts shuttle from space to volcano", "duration": 5 }' ``` ## Image-to-Video Functionality If you want to generate a video based on a reference image or reference video, you can set the parameter `action` to `image2video`, and input the required reference image link or reference video link. Next, you must fill in the prompt words needed for the next step to customize the generated video, specifying the following content: - `model`: The model for generating the video, mainly including `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-i2v-flash`, `wan2.6-t2v` models. - `image_url`: When selecting the image-to-video action `image2video`, you must upload the link to the first frame reference image, currently only supporting models `wan2.6-i2v`, `wan2.6-i2v-flash`. - `reference_video_urls`: Optional when generating video from images, specify the reference video link for generation, currently only supporting model `wan2.6-r2v`. - `prompt`: Prompt words. An example of filling out is as follows:

After filling it out, the code is automatically generated as follows:

The corresponding Python code: ```python import requests url = "https://api.acedata.cloud/wan/videos" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "action": "image2video", "model": "wan2.6-i2v", "prompt": "Astronauts shuttle from space to volcano", "duration": 5, "image_url": "https://cdn.acedata.cloud/r9vsv9.png", "callback_url": "https://www.baidu.com/" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Clicking run, you can find that a result is obtained, as follows: ```json { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } ``` It can be seen that the result content is consistent with the above text, thus achieving the video extension function. ## Asynchronous Callback Since the time taken by the Wan Videos Generation API is relatively long, approximately 1-2 minutes, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the generated video result will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let’s understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own built HTTP server. For demonstration purposes, a public Webhook sample site https://webhook.site/ is used, and opening this site will provide a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/tbcnai.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`. Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the image:

Clicking run, you can find that an immediate result is obtained, as follows: ``` { "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } ``` After a moment, we can observe the generated video result at `https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3`, as shown in the image: ![](https://cdn.acedata.cloud/zv5u2q.png) The content is as follows: ```json { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } ``` It can be seen that the result contains a `task_id` field, and the other fields are similar to the above text, allowing the task to be associated through this field. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Wan Videos Generation API to generate videos by inputting prompt words and the first frame reference image. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. --- # Hailuo Tasks API Integration and Usage The main function of the Hailuo Tasks API is to query the execution status of tasks by inputting the task ID generated by the Hailuo Videos Generation API. This document will provide detailed integration instructions for the Hailuo Tasks API, helping you easily integrate and fully utilize the powerful features of this API. With the Hailuo Tasks API, you can easily query the execution status of tasks from the Hailuo Videos Generation API. ## Application Process To use the Hailuo Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After completing this, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Hailuo Videos Generation API →](https://platform.acedata.cloud/documents/hailuo-videos-integration) ## Request Example The Hailuo Tasks API can be used to query the results of the Hailuo Videos Generation API. For information on how to use the Hailuo Videos Generation API, please refer to the documentation [Hailuo Videos Generation API](https://platform.acedata.cloud/documents/hailuo-videos-generation-integration). We will take a task ID returned by the Hailuo Videos Generation API as an example to demonstrate how to use this API. Suppose we have a task ID: 58cc618b-9639-4ee7-add2-d2fcf260d9a3, and we will demonstrate how to pass in a task ID. ### Task Example Image

### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The uploaded task ID. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: #### CURL ```bash curl -X POST 'https://api.acedata.cloud/hailuo/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "action": "retrieve" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/hailuo/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example Upon successful request, the API will return the detailed information of the video task here. For example: ```json { "_id": "67866dff550a4144a5867aa7", "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470", "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb", "created_at": 1736863231.588, "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636", "request": { "action": "generate", "prompt": "Internal heat" }, "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190", "data": [ { "id": "2a1tbgnjdxrg80cmcmes19s33r", "model": "minimax-t2v", "prompt": "Internal heat", "first_image_url": null, "video_url": "https://platform.cdn.acedata.cloud/czjl/tjU3QYKgU96IJFgpL0eMfBFhmy0qXz9Y05P2IBhShCYaDCFUA/tmp5uligw3a.output.mp4", "state": "succeeded" } ] } } ``` The returned result contains multiple fields, with the request field being the request body when the task was initiated, and the response field being the response body returned after the task is completed. The field descriptions are as follows. - `id`: The ID of the video task generated, used to uniquely identify this video generation task. - `request`: The request information in the video task. - `response`: The return information in the video task. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The task execution start time, Unix timestamp (seconds, float). - `finished_at`: The task completion time, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation This is for querying the details of multiple task IDs, and unlike the above, the action needs to be selected as retrieve_batch. **Request Body** includes: - `ids`: An array of uploaded task IDs. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: ### Response Example Upon successful request, the API will return the specific details of all batch video tasks this time. For example: ```json { "items": [ { "_id": "67866fad550a4144a587053c", "id": "09d4a93e-d5c8-4778-bdf2-711773d71c59", "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470", "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb", "created_at": 1736863661.511, "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636", "request": { "action": "generate", "prompt": "Internal heat" }, "trace_id": "0edc94c6-4938-4bff-bb16-20364c254e40", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "09d4a93e-d5c8-4778-bdf2-711773d71c59", "trace_id": "0edc94c6-4938-4bff-bb16-20364c254e40", "data": [ { "id": "24zdgea0s1rge0cmcmjbsfj2m8", "model": "minimax-t2v", "prompt": "Internal heat", "first_image_url": null, "video_url": "https://platform.cdn.acedata.cloud/czjl/6cTYBRBDVJIQANzG7GaPwPblbeIiFe4yUDcVoMkkXttqJCFUA/tmpm4ke45c5.output.mp4", "state": "succeeded" } ] } }, { "_id": "67866dff550a4144a5867aa7", "id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "api_id": "d5af91f6-a7ec-4015-b0a5-d25051158470", "application_id": "2f9f4d93-9193-4c49-a1a5-eddf0ff38abb", "created_at": 1736863231.588, "credential_id": "f634e655-012e-432e-92a8-a87e4a80d636", "request": { "action": "generate", "prompt": "Internal heat" }, "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "58cc618b-9639-4ee7-add2-d2fcf260d9a3", "trace_id": "0c1f9f13-0aef-4d9a-a9d2-1d27055ff190", "data": [ { "id": "2a1tbgnjdxrg80cmcmes19s33r", "model": "minimax-t2v", "prompt": "Internal heat", "first_image_url": null, "video_url": "https://platform.cdn.acedata.cloud/czjl/tjU3QYKgU96IJFgpL0eMfBFhmy0qXz9Y05P2IBhShCYaDCFUA/tmp5uligw3a.output.mp4", "state": "succeeded" } ] } } ], "count": 2 } ``` The returned result contains multiple fields, among which `items` includes the specific details of batch video tasks, and the specific information of each video task is the same as the format of the single task return result mentioned above. The field information is as follows. - `items`, all specific detail information of batch video tasks. It is an array, and each element of the array has the same format as the return result of querying a single task above. - `count`, the number of video tasks in this batch query. #### CURL ```bash curl -X POST 'https://api.acedata.cloud/hailuo/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["09d4a93e-d5c8-4778-bdf2-711773d71c59","58cc618b-9639-4ee7-add2-d2fcf260d9a3"], "action": "retrieve_batch" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/hailuo/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "ids": ["09d4a93e-d5c8-4778-bdf2-711773d71c59","58cc618b-9639-4ee7-add2-d2fcf260d9a3"], "action": "retrieve_batch" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Hailuo Tasks API to query all specific detail information of single or batch video tasks. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. --- # HappyHorse Tasks API Integration and Usage The HappyHorse Tasks API is used to query the video generation or editing tasks created by the HappyHorse Videos API. ## Application Process To use the HappyHorse Videos API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [HappyHorse Videos API →](https://platform.acedata.cloud/documents/happyhorse-videos) ## Request Example The HappyHorse Tasks API can be used to query the results of the HappyHorse Videos API. ### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response result should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The task ID to query. - `action`: The operation method for the task, set to `retrieve` for a single query. ### CURL Code Example ```bash curl -X POST 'https://api.acedata.cloud/happyhorse/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "action": "retrieve" }' ``` ### Response Example Upon successful request, the API will return the details of the task. The `request` field contains the request body when the task was created, and the `response` field contains the response body returned after the task is completed, for example: ```json { "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "started_at": 1769262721.823, "finished_at": 1769262774.423, "elapsed": 52.6, "request": { "action": "generate", "model": "happyhorse-1.1-t2v", "prompt": "A cinematic shot of a white horse running across a moonlit beach", "resolution": "720P", "duration": 5 }, "type": "videos", "response": { "success": true, "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea", "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2", "data": [ { "id": "1469cfc3-3004-4d9e-ab10-xxxxxx", "video_url": "https://cdn.acedata.cloud/happyhorse/c8cbf53aa0.mp4", "state": "succeeded", "duration": 5, "resolution": "720P", "ratio": "16:9" } ] } } ``` Field descriptions are as follows: - `id`: The ID of the generated task, used to uniquely identify this generation task. - `request`: The request information when the task was created. - `response`: The current or final return information of the task. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The time the task started executing, Unix timestamp (seconds, float). - `finished_at`: The time the task was completed, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for the task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation When querying task details for multiple task IDs, set the `action` to `retrieve_batch` and pass the task ID array through `ids`: ```bash curl -X POST 'https://api.acedata.cloud/happyhorse/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["b8976e18-32dc-4718-9ed8-1ea090fcb6ea"], "action": "retrieve_batch" }' ``` The returned result will include the `items` and `count` fields, where `items` is the array of task details, and `count` is the number of tasks matched in this query. --- # Kling Tasks API Integration and Usage The main function of the Kling Tasks API is to query the execution status of tasks by inputting the task ID generated by the Kling Videos Generation API. This document will provide detailed instructions for integrating the Kling Tasks API, helping you easily leverage the powerful features of this API. With the Kling Tasks API, you can easily query the execution status of tasks from the Kling Videos Generation API. ## Application Process To use the Kling Videos Generation API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and will return to the current page automatically after completion. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Kling Videos Generation API →](https://platform.acedata.cloud/documents/kling-videos) ## Request Example The Kling Tasks API can be used to query the results of the Kling Videos Generation API. For how to use the Kling Videos Generation API, please refer to the documentation [Kling Videos Generation API](https://platform.acedata.cloud/documents/kling-videos). We will demonstrate how to use this API with an example task ID returned by the Kling Videos Generation API. Suppose we have a task ID: 20068983-0cc9-4c6a-aeb6-9c6a3c668be0, we will show how to pass in a task ID. ### Task Example Image

### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response result should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The uploaded task ID. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: #### CURL ```bash curl -X POST 'https://api.acedata.cloud/kling/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0", "action": "retrieve" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/kling/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example Upon successful request, the API will return the detailed information of the video task here. For example: ```json { "_id": "67c5163f550a4144a5b68698", "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0", "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb", "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2", "created_at": 1740969535.333, "started_at": 1740969535.393, "finished_at": 1740969852.463, "elapsed": 317.07, "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220", "request": { "action": "text2video", "model": "kling-v1", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3" }, "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "CjJzzGfBfqcAAAAAAKdVMQ", "response": { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } } ``` The returned result contains multiple fields, the request field is the request body when the task was initiated, while the response field is the response body returned after the task is completed. The field descriptions are as follows. - `id`: The ID of the video task generated, used to uniquely identify this video generation task. - `request`: The request information in the video task. - `response`: The return information in the video task. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The task execution start time, Unix timestamp (seconds, float). - `finished_at`: The task completion time, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation This is for querying the details of multiple task IDs, and unlike the above, the action needs to be selected as retrieve_batch. **Request Body** includes: - `ids`: An array of uploaded task IDs. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: ### Response Example Upon successful request, the API will return the specific details of all batch video tasks this time. For example: ```json { "items": [ { "_id": "67c5163f550a4144a5b68698", "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0", "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb", "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2", "created_at": 1740969535.333, "started_at": 1740969535.393, "finished_at": 1740969852.463, "elapsed": 317.07, "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220", "request": { "action": "text2video", "model": "kling-v1", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.", "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3" }, "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "CjJzzGfBfqcAAAAAAKdVMQ", "response": { "success": true, "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0" } }, { "_id": "67c51415550a4144a5b442a5", "id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0", "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb", "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2", "created_at": 1740968981.619, "started_at": 1740968981.679, "finished_at": 1740969297.937, "elapsed": 316.258, "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220", "request": { "action": "text2video", "model": "kling-v1", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }, "trace_id": "4f32ba2d-8846-4ea9-9253-997ec0b2e052", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "Cjil4mfBfs0AAAAAAKbMQQ", "response": { "success": true, "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508", "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4", "duration": "5.1", "state": "succeed", "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0" } } ], "count": 2 } ``` #### CURL ```bash curl -X POST 'https://api.acedata.cloud/kling/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["e3a575aa-a4bd-49c8-9b12-cde38d5462e0","20068983-0cc9-4c6a-aeb6-9c6a3c668be0"], "action": "retrieve_batch" }' ``` ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Kling Tasks API to query the specific details of single or batch video tasks. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Maestro Task Query API Integration Instructions The main function of the Maestro Task Query API is to query the execution status and final results of a task using the task ID returned by the [Maestro Video Generation API](development_maestro_videos.md) (`POST /maestro/videos`). This document will provide detailed instructions for integrating the Maestro Task Query API. Since video generation is an asynchronous task, after submission, this interface needs to be polled to obtain progress and the final product, **polling is free and does not consume credits.** `POST https://api.acedata.cloud/maestro/tasks` ## Application Process To use the Maestro Task Query API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete documentation: [Maestro Task Query API →](https://platform.acedata.cloud/documents/maestro-tasks) ## Query a Single Task For information on how to create a video task, please refer to the document [Maestro Video Generation API](development_maestro_videos.md). We will use a task ID returned by it as an example: `f57e99c4f60f4373a15517742ce2357d`, demonstrating how to query its status and results. ### Set Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response result should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. - `content-type`: The format of the request body, set to `application/json`. **Request Body** includes: | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------------------------------- | | `id` | string | Yes | The `task_id` returned by `POST /maestro/videos` | | `action` | string | No | `retrieve` (default, query a single task) / `retrieve_batch` (query historical task list) | ### Code Example The corresponding CURL code is as follows: ```bash curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "f57e99c4f60f4373a15517742ce2357d", "action": "retrieve" }' ``` The corresponding Python code is as follows: ```python import requests url = "https://api.acedata.cloud/maestro/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "f57e99c4f60f4373a15517742ce2357d", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example After a successful request, the API will return the status and results of the video task. An example of the return when the task is completed is as follows (each language corresponds to a `variant`): ```json { "id": "f57e99c4f60f4373a15517742ce2357d", "started_at": 1769262721.823, "finished_at": 1769264698.3, "elapsed": 1976.477, "status": "succeeded", "progress": { "percent": 100, "stage": "producing", "message": "rendering scene 2" }, "request": { "prompt": "Explain what a vector database is in 20 seconds, suitable for a zero-based audience, and end with a memorable point", "langs": [ "zh-cn", "en" ], "aspect": "9:16", "duration": 20 }, "response": { "success": true, "data": { "variants": [ { "lang": "zh-cn", "aspect": "9:16", "kind": "video", "title": "什么是向量数据库", "output_url": "https://…/zh.mp4" }, { "lang": "en", "aspect": "9:16", "kind": "video", "title": "What is a vector database", "output_url": "https://…/en.mp4" } ], "project": { "tarball_url": "https://…/project.tar.gz", "outputs": [ "https://…/zh.mp4", "https://…/en.mp4" ] }, "percent": 100, "stage": "producing", "progress": [ { "stage": "producing", "message": "rendering scene 2", "pct": 60, "t": 1750000000 } ] } } } ``` The field descriptions of the returned result are as follows: - `id`: The ID of this video task, used to uniquely identify this video generation task. - `status`: The task status, with values `pending → planning → producing → succeeded` (or `failed`). Whether the task is completed is determined by this top-level `status`. - `elapsed`: The time spent on the task (in seconds). - `progress`: The top-level progress object, `percent` (0–100) will be capped at 100 after the task is successful; `stage` and `message` reflect the most recent progress event from the AI director (thus after success, `stage` may still be the last executed stage such as `producing`), which can be directly used to display a progress bar. - `request`: The request body when initiating the task. - `response`: The return information of the task. - `success`: Whether the task was successful. - `data.variants`: Each language corresponds to a final product object, containing `lang`, `aspect`, `title`, `output_url` (download link for the final product), etc. - `data.project`: The entire project output, containing `tarball_url` (project package) and `outputs` (all final product links). - `data.progress`: An array of progress events appended by stage (append-only log), which can be used to display detailed real-time progress. - `created_at`: The task creation time, Unix timestamp (in seconds). - `started_at`: The time the task started execution, Unix timestamp (in seconds). It is null when the task has not yet started. - `finished_at`: The time the task was completed, Unix timestamp (in seconds). It is null when the task is not completed. ## Query Historical List By passing `action: retrieve_batch`, you can obtain the recent tasks of the current user (in reverse order of creation time), which can be used for the "My Videos" list page. **Request Body** includes: | Field | Type | Required | Description | | ------------------- | -------- | -------- | ------------------------------------ | | `action` | string | Yes | Fixed as `retrieve_batch` | | `limit` | int | No | Number of returns, default is 20 | | `created_at_max` | int | No | Only return tasks earlier than this Unix timestamp (for pagination) | | `created_at_min` | int | No | Only return tasks later than this Unix timestamp | ### Code Example The corresponding CURL code is as follows: ```bash curl -X POST 'https://api.acedata.cloud/maestro/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "action": "retrieve_batch", "limit": 20 }' ``` ### Response Example After a successful request, the API will return the current user's history task list: ```json { "count": 2, "items": [ { "id": "f57e99c4f60f4373a15517742ce2357d", "started_at": 1769262721.823, "finished_at": 1769264698.3, "elapsed": 1976.477, "status": "succeeded", "progress": { "percent": 100, "stage": "producing", "message": "rendering scene 2" }, "request": { "prompt": "…", "langs": [ "zh-cn", "en" ], "aspect": "9:16", "duration": 20 }, "response": { "success": true, "data": { "variants": [ { "lang": "zh-cn", "output_url": "https://…/zh.mp4" } ] } } } ] } ``` The fields in the returned result are described as follows: - `count`: The total number of tasks for the current user. - `items`: An array of tasks, where each element's format is consistent with the return result of "query a single task". ## Polling Suggestions Since video production takes a long time, the `status` will go through `pending → planning → producing → succeeded` (or `failed`). It is recommended to poll every 5–10 seconds until the `status` changes to `succeeded` or `failed`. You can use the top-level `progress.percent` to display a real-time progress bar. **Polling this interface is free and does not consume points.** ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `404 not_found`: Task not found, the given task_id does not exist. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Maestro task query API to check the status and results of a single task, as well as to pull the current user's history task list. We hope this document helps you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. ## Related Interfaces - [Maestro Video Generation API Integration Instructions](development_maestro_videos.md): Automatically produce subtitled videos with a natural language prompt, return `task_id` after submission, and then use this interface to poll the results. --- # MiniMax H3 Task Query API Integration Guide This document introduces the integration and usage of the MiniMax H3 Task Query API. This interface is used to query, batch list, or delete asynchronous tasks created by the [MiniMax H3 Video Generation API](/documents/minimax-videos-integration). ## Application Process To use the MiniMax H3 Task Query API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, after which you will be automatically returned to the current page. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete documentation: [MiniMax H3 Task Query API →](https://platform.acedata.cloud/documents/minimax-tasks-integration) When querying tasks, you should use the same Token that was used to create the task. It is recommended to save the Token as an environment variable and not to write it into the source code or submit it to the version repository: ```bash export ACEDATACLOUD_API_KEY="YOUR_API_KEY" ``` ## Interface Overview - **Base URL**: `https://api.acedata.cloud` - **Endpoint**: `POST /minimax/tasks` - **Authentication Method**: Include `authorization: Bearer {token}` in the HTTP Header - **Request Headers**: - `accept: application/json` - `content-type: application/json` - **Query a Single Task**: `action=retrieve`, pass in `id` - **Batch Query Tasks**: `action=retrieve_batch`, can filter by task ID, time range, and pagination conditions - **Delete Task**: `action=delete`, pass in `id` - **Billing Description**: Task queries are free and will not incur duplicate billing After creating a video, you must save the `task_id`. It is recommended to query approximately every 10 seconds until the task enters a terminal state. ## Request Parameters | Parameter | Type | Required | Applicable Actions | Description | | ------------------ | --------- | -------- | -------------------------- | ---------------------------------------------------- | | `action` | string | No | All | `retrieve`, `retrieve_batch`, or `delete`; default is `retrieve` | | `id` | string | Conditionally Required | `retrieve`, `delete` | Single task ID | | `ids` | string[] | No | `retrieve_batch` | Only return specified task IDs; omitted will list tasks by other conditions | | `limit` | integer | No | `retrieve_batch` | Maximum number of tasks to return this time | | `offset` | integer | No | `retrieve_batch` | Number of tasks to skip from the result list, used for pagination | | `created_at_min` | number | No | `retrieve_batch` | Creation time lower limit, Unix timestamp, in seconds | | `created_at_max` | number | No | `retrieve_batch` | Creation time upper limit, Unix timestamp, in seconds | The purposes of the three actions are as follows: | `action` | Purpose | Required Parameters | Response Structure | | ------------------ | ------------------------------- | ------------------------------------ | --------------------------------------------- | | `retrieve` | Query the status and result of a task | `id` | `{ "task": {...} }` | | `retrieve_batch` | Batch query by task ID, time, and pagination conditions | Optional `ids`, time range, `offset`, `limit` | `{ "items": [...], "total": number }` | | `delete` | Cancel or delete task record based on the current status | `id` | `{ "id": "...", "deleted": true }` | ## Query a Single Task ```bash curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "retrieve", "id": "f5977217-ed2c-40da-adbe-93d08235618f" }' ``` Below is a response from a real successful task: ```json { "task": { "id": "f5977217-ed2c-40da-adbe-93d08235618f", "model": "MiniMax-H3", "status": "succeeded", "created_at": 1786184658, "updated_at": 1786184758, "content": { "url": "https://platform2.cdn.acedata.cloud/minimax/f5977217-ed2c-40da-adbe-93d08235618f.mp4" }, "resolution": "768P", "duration": 4, "usage": { "total_seconds": 4, "input_seconds": 0, "output_seconds": 4, "input_image_count": 0 }, "ratio": "16:9", "task_type": "generation", "modality": "video" } } ``` [Open the real video result of this task](https://platform2.cdn.acedata.cloud/minimax/f5977217-ed2c-40da-adbe-93d08235618f.mp4) ## Task Status | `status` | Meaning | Client Handling | | ----------- | --------------------------- | -------------------------------- | | `queued` | Entered the queue, waiting for execution | Continue polling | | `running` | Currently generating | Continue polling | | `succeeded` | Generation succeeded | Read `task.content.url`, stop polling | | `failed` | Generation failed | Read `task.error`, stop polling | | `cancelled` | Task has been cancelled | Stop polling | `succeeded`, `failed`, and `cancelled` are all terminal states. Do not continue polling after entering a terminal state. ## Task Response Fields | Field | Type | Description | | ------------------------- | -------- | ------------------------------------ | | `id` | string | Task ID | | `model` | string | Model used for the task, currently `MiniMax-H3` | | `status` | string | Current task status | | `error.code` | string | Failure error code, returned only on failure | | `error.message` | string | Reason for failure, returned only on failure | | `created_at` | integer | Creation time, Unix timestamp, in seconds | | `updated_at` | integer | Last status update time, Unix timestamp, in seconds | | `content.url` | string | Video address after success | | `resolution` | string | Output resolution, `768P` or `2K` | | `duration` | integer | Output video duration, in seconds | | `usage.total_seconds` | integer | Total cost amount, equal to the sum of input video seconds and output seconds | | `usage.input_seconds` | integer | Cost amount generated by the input reference video | | `usage.output_seconds` | integer | Cost amount generated by the output video | | `usage.input_image_count` | integer | Number of input images in billing statistics | | `ratio` | string | Actual output aspect ratio; when using `adaptive`, this result is authoritative | | `task_type` | string | Video generation task is `generation` | | `modality` | string | Video task is `video` | ## Python Polling Complete Example The following code reads the Token from environment variables and queries every 10 seconds after creating a task: ```python import os import time import requests BASE_URL = "https://api.acedata.cloud" HEADERS = { "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}", "Content-Type": "application/json", } create_response = requests.post( f"{BASE_URL}/minimax/videos", headers=HEADERS, json={ "model": "MiniMax-H3", "content": [ { "type": "text", "text": "In the early morning by the sea, a white sailboat glides across the calm surface of the water, the camera slowly pans.", } ], "resolution": "768P", "duration": 4, "ratio": "16:9", }, timeout=30, ) create_response.raise_for_status() task_id = create_response.json()["task_id"] while True: time.sleep(10) query_response = requests.post( f"{BASE_URL}/minimax/tasks", headers=HEADERS, json={"action": "retrieve", "id": task_id}, timeout=30, ) query_response.raise_for_status() task = query_response.json()["task"] print(f"task={task_id} status={task['status']}") if task["status"] == "succeeded": print(f"video_url={task['content']['url']}") break if task["status"] in ("failed", "cancelled"): raise RuntimeError(task.get("error") or task["status"]) ``` The production environment should set a total timeout for polling and use exponential backoff for `429` and temporary `5xx`. Network timeouts do not equal generation failures, and the same `task_id` can be used to continue querying. ## Batch Query Specify multiple task IDs: ```bash curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "retrieve_batch", "ids": ["TASK_ID_1", "TASK_ID_2"], "offset": 0, "limit": 20 }' ``` List tasks by time range with pagination: ```json { "action": "retrieve_batch", "created_at_min": 1786000000, "created_at_max": 1786200000, "offset": 0, "limit": 20 } ``` In the batch response, `items` use the same task fields as a single task query, and `total` is the total number of tasks matching the filter criteria: ```json { "items": [ { "id": "TASK_ID_1", "model": "MiniMax-H3", "status": "running", "resolution": "2K", "duration": 5, "ratio": "adaptive", "task_type": "generation", "modality": "video" } ], "total": 1 } ``` The task query window is the last 7 days. `task_id` beyond this window may return invalid tasks; the business system should save the ID when creating the task and promptly persist the result URL upon success. ## Cancel or Delete Task ```bash curl -X POST 'https://api.acedata.cloud/minimax/tasks' \ -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "action": "delete", "id": "YOUR_TASK_ID" }' ``` The action depends on the current status of the task: | Current Status | Action | | -------------- | ------------------------------- | | `queued` | Cancel tasks that have not started yet | | `succeeded` | Delete task record | | `failed` | Delete task record | | `running` | Deletion or cancellation not allowed, return error | | `cancelled` | Repeated operation not allowed, return error | Example of successful deletion: ```json { "id": "YOUR_TASK_ID", "deleted": true } ``` Deleting a task record does not reverse any completed billing, nor can it guarantee that saved video copies are deleted simultaneously. ## Failure Response and Troubleshooting Failed tasks still return a task object with HTTP 200, and the reason is given in `task.error`: ```json { "task": { "id": "YOUR_TASK_ID", "model": "MiniMax-H3", "status": "failed", "error": { "code": "1026", "message": "video description contains sensitive content" }, "task_type": "generation", "modality": "video" } } ``` If the interface itself returns `400`, check the `action` and condition parameters; `401` indicates an invalid Token, `429` indicates queries are too frequent, and `500` indicates the service is temporarily unavailable. Tasks that fail to generate are not billed; successful tasks are recorded based on the final `usage`. --- # Nano Banana Tasks API Integration and Usage The main function of the Nano Banana Tasks API is to query the execution status of a task by inputting the task ID generated by the Nano Banana Images API. This document will provide detailed integration instructions for the Nano Banana Tasks API, helping you easily integrate and fully utilize the powerful features of this API. With the Nano Banana Tasks API, you can easily query the execution status of tasks from the Nano Banana Images API. ## Request Example The Nano Banana Tasks API can be used to query the results of the Nano Banana Images API. For information on how to use the Nano Banana Images API, please refer to the documentation [Nano Banana Images API](https://platform.acedata.cloud/documents/veo-videos). We will take a task ID returned by the Nano Banana Images API as an example to demonstrate how to use this API. Suppose we have a task ID: 4d320ead-4af4-4a55-8f3e-f2afebdf4fd0, and we will demonstrate how to pass in a task ID. ### Task Example Image

### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The uploaded task ID. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example It can be seen that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: #### CURL ```bash curl -X POST 'https://api.acedata.cloud/nano-banana/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "action": "retrieve" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/nano-banana/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example Upon successful request, the API will return the details of the task here. For example: ```json { "_id": "68bc7c3c550a4144a53d0e24", "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610", "application_id": "8afd681a-2a4e-4265-aecb-43970094c019", "created_at": 1757183036.787, "started_at": 1757183036.847, "finished_at": 1757183048.147, "elapsed": 11.3, "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07", "request": { "action": "generate", "prompt": "a white siamese cat" }, "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319", "type": "images", "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6", "response": { "success": true, "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319", "data": [ { "prompt": "a white siamese cat", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png" } ] } } ``` The returned result contains multiple fields, the request field is the request body when the task was initiated, while the response field is the response body returned after the task is completed. The field descriptions are as follows. - `id`: The ID of the generated task, used to uniquely identify this generation task. - `request`: The request information in the task query. - `response`: The return information in the task query. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The task execution start time, Unix timestamp (seconds, float). - `finished_at`: The task completion time, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation This is for querying task details for multiple task IDs, and unlike the above, the action needs to be selected as `retrieve_batch`. **Request Body** includes: - `ids`: An array of uploaded task IDs. - `action`: The operation method for the task. Example as follows: ```bash curl -X POST 'https://api.acedata.cloud/nano-banana/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"], "action": "retrieve_batch" }' ``` ### Response Example Upon successful request, the API will return the specific details of all batch tasks this time. For example: ```json { "items": [ { "_id": "68bc7c3c550a4144a53d0e24", "id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "api_id": "9d8a117e-31ca-4322-a0fd-1771296ec610", "application_id": "8afd681a-2a4e-4265-aecb-43970094c019", "created_at": 1757183036.787, "started_at": 1757183036.847, "finished_at": 1757183048.147, "elapsed": 11.3, "credential_id": "097b2987-62f4-4ac0-b0cc-aed41e372a07", "request": { "action": "generate", "prompt": "a white siamese cat" }, "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319", "type": "images", "user_id": "b87f67c1-b04f-4332-99a1-7a5e651331c6", "response": { "success": true, "task_id": "4d320ead-4af4-4a55-8f3e-f2afebdf4fd0", "trace_id": "7ba1f1e8-0ef8-450d-8bb2-b5c3bf1ea319", "data": [ { "prompt": "a white siamese cat", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/7e7bd000-698a-4e14-bb2d-3db61237e4bb.png" } ] } } ], "count": 1 } ``` The return result contains multiple fields, among which items include the specific details of batch tasks, and the specific information of each task is the same as the fields above. - `items`, all specific detail information of batch tasks. It is an array, and each element of the array has the same format as the return result of querying a single task above. - `count`, the number of batch query tasks here. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Nano Banana Tasks API to query all specific detail information of single or batch tasks. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. --- # Producer Upload Reference Audio API Integration Instructions Producer allows us to upload reference audio for secondary creation. This document explains the integration method of the related API. This API has only one input parameter, which is `audio_url`, a publicly accessible CDN address that supports the mp3 suffix. The `audio_url` we input is `https://cdn.acedata.cloud/suno_demo.mp3`, which is a publicly accessible CDN address. ```bash curl -X POST 'https://api.acedata.cloud/producer/upload' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3" }' ``` The result is as follows: ``` { "success": true, "task_id": "23e7d4ec-d1a8-429f-87d8-9f53fc3b6666", "data": { "audio_id": "d906da31-87cb-42f5-98df-2fc4969923b1", "lyric": "[Mandopop, Acoustic Pop]\n[Soft female vocals, bright and cheerful]\n\n[Verse 1]\nThe sunlight shines on the beach\nThe waves laugh brightly\nYou and I on the sand\nThe clock stops ticking\nThe ice cream is melting\nHand in hand for a walk\nThe wind gently blows\nThe heartbeat keeps beating\n\n[Chorus]\nSummer summer\nTime stops on this day\nLaughter echoes\nThe blue sky is beside us", "audio_url": "https://storage.googleapis.com/corpusant-app-public/producer/raw/d906da31-87cb-42f5-98df-2fc4969923b1.mp3" } } ``` As can be seen, the `audio_id` field in `data` is the song ID after uploading. With the song ID, we can use the [Producer Audios Generation API](https://platform.acedata.cloud/documents/producer-audios-integration) to generate custom songs. For example, by passing `action` as `upload_extend` and `audio_id` as the returned song ID, we can generate a new song based on the reference audio. --- # Integration and Use of Veo Tasks API The main function of the Veo Tasks API is to query the execution status of a task by inputting the task ID generated by the Veo Videos Generation API. This document will provide detailed integration instructions for the Veo Tasks API, helping you easily integrate and fully utilize the powerful features of this API. With the Veo Tasks API, you can easily query the execution status of tasks from the Veo Videos Generation API. ## Application Process To use the Veo Videos Generation API, first obtain your API Token from the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) for future reference. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in, and will return to the current page upon completion. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Veo Videos Generation API →](https://platform.acedata.cloud/documents/veo-videos) ## Request Example The Veo Tasks API can be used to query the results of the Veo Videos Generation API. For information on how to use the Veo Videos Generation API, please refer to the documentation [Veo Videos Generation API](https://platform.acedata.cloud/documents/veo-videos). We will demonstrate how to use this API with an example task ID returned by the Veo Videos Generation API. Suppose we have a task ID: 1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed, we will demonstrate how to pass in a task ID. ### Task Example Image

### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response result should be in JSON format, set to `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The uploaded task ID. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: #### CURL ```bash curl -X POST 'https://api.acedata.cloud/veo/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "action": "retrieve" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/veo/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example Upon successful request, the API will return the details of the video task here. For example: ```json { "_id": "68834c16550a4144a5112589", "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46", "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2", "created_at": 1753435158.509, "started_at": 1753435158.569, "finished_at": 1753435250.969, "elapsed": 92.4, "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae", "request": { "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc", "action": "text2video", "model": "veo2-fast", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }, "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "data": [ { "id": "2f43ceed37944b4d836e1a1899dad0a1", "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4", "created_at": "2025-07-25 17:19:20", "complete_at": "2025-07-25 17:21:45", "state": "succeeded" } ] } } ``` The returned result contains multiple fields, with the request field being the request body when the task was initiated, and the response field being the response body returned after the task is completed. The field descriptions are as follows. - `id`: The ID of the video task generated, used to uniquely identify this video generation task. - `request`: The request information in the video task. - `response`: The return information in the video task. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The task execution start time, Unix timestamp (seconds, float). - `finished_at`: The task completion time, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation This is for querying the details of multiple task IDs, and unlike the above, the action needs to be selected as retrieve_batch. **Request Body** includes: - `ids`: An array of uploaded task IDs. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example You can see that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: ### Response Example Upon successful request, the API will return the specific details of all batch video tasks this time. For example: ```json { "items": [ { "_id": "68834c16550a4144a5112589", "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46", "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2", "created_at": 1753435158.509, "started_at": 1753435158.569, "finished_at": 1753435250.969, "elapsed": 92.4, "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae", "request": { "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc", "action": "text2video", "model": "veo2-fast", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }, "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "data": [ { "id": "2f43ceed37944b4d836e1a1899dad0a1", "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4", "created_at": "2025-07-25 17:19:20", "complete_at": "2025-07-25 17:21:45", "state": "succeeded" } ] } }, { "_id": "68834c16550a4144a5112589", "id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "api_id": "52a0fa83-3c78-4793-b45a-c1a5c869ae46", "application_id": "b7341df0-3a87-40ef-8f3c-a7dda97816a2", "created_at": 1753435158.509, "started_at": 1753435158.569, "finished_at": 1753435250.969, "elapsed": 92.4, "credential_id": "1f64eaaa-eff0-4f18-bfc2-8c5b1e7949ae", "request": { "callback_url": "https://webhook.site/aed5cd28-f8aa-4dca-9480-8ec9b42137dc", "action": "text2video", "model": "veo2-fast", "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle." }, "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "response": { "success": true, "task_id": "1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed", "trace_id": "d1d53c04-58c5-4c40-bb63-f00188540e56", "data": [ { "id": "2f43ceed37944b4d836e1a1899dad0a1", "video_url": "https://platform.cdn.acedata.cloud/veo/1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed.mp4", "created_at": "2025-07-25 17:19:20", "complete_at": "2025-07-25 17:21:45", "state": "succeeded" } ] } } ], "count": 2 } ``` The returned result contains multiple fields, among which `items` includes the specific details of batch video tasks, and the specific information of each video task is the same as the fields in the previous single task query result. - `items`, all specific detail information of batch video tasks. It is an array, and each element of the array has the same format as the previous single task return result. - `count`, the number of video tasks in this batch query. #### CURL ```bash curl -X POST 'https://api.acedata.cloud/veo/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed","1ebe4f2b-59ba-4385-a4ea-0ce8a3fe12ed"], "action": "retrieve_batch" }' ``` ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Veo Tasks API to query all specific detail information of single or batch video tasks. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team. --- # Wan Tasks API Integration and Usage The main function of the Wan Tasks API is to query the execution status of tasks by inputting the task ID generated by the Wan Videos Generation API. This document will provide a detailed description of the Wan Tasks API integration, helping you easily integrate and fully utilize the powerful features of this API. With the Wan Tasks API, you can easily query the execution status of tasks from the Wan Videos Generation API. ## Application Process To use the Wan Videos Generation API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for future use. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete Documentation: [Wan Videos Generation API →](https://platform.acedata.cloud/documents/wan-videos) ## Request Example The Wan Tasks API can be used to query the results of the Wan Videos Generation API. For how to use the Wan Videos Generation API, please refer to the documentation [Wan Videos Generation API](https://platform.acedata.cloud/documents/wan-videos). We will take a task ID returned by the Wan Videos Generation API as an example to demonstrate how to use this API. Suppose we have a task ID: a4bca552-d964-46a1-8ff7-fd922f916582, and we will demonstrate how to pass in a task ID. ### Task Example Image

### Setting Request Headers and Request Body **Request Headers** include: - `accept`: Specifies that the response result should be in JSON format, filled in as `application/json`. - `authorization`: The key to call the API, which can be selected directly after application. **Request Body** includes: - `id`: The uploaded task ID. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example It can be seen that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: #### CURL ```bash curl -X POST 'https://api.acedata.cloud/wan/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "id": "a4bca552-d964-46a1-8ff7-fd922f916582", "action": "retrieve" }' ``` #### Python ```python import requests url = "https://api.acedata.cloud/wan/tasks" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "id": "a4bca552-d964-46a1-8ff7-fd922f916582", "action": "retrieve" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ### Response Example Upon successful request, the API will return the detailed information of the video task here. For example: ```json { "_id": "6974ce81ff2676299c399252", "id": "a4bca552-d964-46a1-8ff7-fd922f916582", "api_id": "6a4ecdbf-b219-4505-8277-5ec4b1ac14f8", "application_id": "52933893-8e8b-4cd6-b9e5-2354eedea000", "created_at": 1769262721.763, "started_at": 1769262721.823, "finished_at": 1769263509.094, "elapsed": 787.271, "credential_id": "c7173d71-d234-413e-ab72-7bfa6715d12f", "request": { "action": "text2video", "model": "wan2.6-t2v", "prompt": "Astronauts shuttle from space to volcano", "duration": 5 }, "trace_id": "b9cf9569-4010-46b1-80ec-efc881126eac", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "0d2042f9-ba8d-496d-8ab5-182617e28f9e", "response": { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu%2Fx7BYCFQk0s%3D", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } } ``` The returned result contains multiple fields, the request field is the request body when the task was initiated, while the response field is the response body returned after the task is completed. The field descriptions are as follows. - `id`: The ID of the video task generated, used to uniquely identify this video generation task. - `request`: The request information in the video task. - `response`: The return information in the video task. - `created_at`: The task creation time, Unix timestamp (seconds, float). - `started_at`: The task start execution time, Unix timestamp (seconds, float). - `finished_at`: The task completion time, Unix timestamp (seconds, float). This field is not returned if the task is not completed. - `elapsed`: The time taken for task execution, in seconds (float, rounded to 3 decimal places). This field is not returned if the task is not completed. ## Batch Query Operation This is for querying the details of multiple task IDs, and unlike the above, the action needs to be selected as retrieve_batch. **Request Body** includes: - `ids`: An array of uploaded task IDs. - `action`: The operation method for the task. Set as shown in the image below:

### Code Example It can be seen that various language codes have been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows: ### Response Example Upon successful request, the API will return the specific details of all batch video tasks this time. For example: ```json { "items": [ { "_id": "6974ce81ff2676299c399252", "id": "a4bca552-d964-46a1-8ff7-fd922f916582", "api_id": "6a4ecdbf-b219-4505-8277-5ec4b1ac14f8", "application_id": "52933893-8e8b-4cd6-b9e5-2354eedea000", "created_at": 1769262721.763, "started_at": 1769262721.823, "finished_at": 1769263509.094, "elapsed": 787.271, "credential_id": "c7173d71-d234-413e-ab72-7bfa6715d12f", "request": { "action": "text2video", "model": "wan2.6-t2v", "prompt": "Astronauts shuttle from space to volcano", "duration": 5 }, "trace_id": "b9cf9569-4010-46b1-80ec-efc881126eac", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "0d2042f9-ba8d-496d-8ab5-182617e28f9e", "response": { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu%2Fx7BYCFQk0s%3D", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } }, { "_id": "6974ce81ff2676299c399252", "id": "a4bca552-d964-46a1-8ff7-fd922f916582", "api_id": "6a4ecdbf-b219-4505-8277-5ec4b1ac14f8", "application_id": "52933893-8e8b-4cd6-b9e5-2354eedea000", "created_at": 1769262721.763, "started_at": 1769262721.823, "finished_at": 1769263509.094, "elapsed": 787.271, "credential_id": "c7173d71-d234-413e-ab72-7bfa6715d12f", "request": { "action": "text2video", "model": "wan2.6-t2v", "prompt": "Astronauts shuttle from space to volcano", "duration": 5 }, "trace_id": "b9cf9569-4010-46b1-80ec-efc881126eac", "type": "videos", "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf", "job_id": "0d2042f9-ba8d-496d-8ab5-182617e28f9e", "response": { "success": true, "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu%2Fx7BYCFQk0s%3D", "state": "completed", "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582" } } ], "count": 2 } ``` #### CURL ```bash curl -X POST 'https://api.acedata.cloud/wan/tasks' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "ids": ["a4bca552-d964-46a1-8ff7-fd922f916582","a4bca552-d964-46a1-8ff7-fd922f916582"], "action": "retrieve_batch" }' ``` ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to use the Wan Tasks API to query the specific details of single or batch video tasks. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # OpenAI Images Generations API Application and Usage The OpenAI Images Generations API currently supports various image generation models, including the classic `dall-e-3`, the text rendering-capable `gpt-image-1`, the latest generation **`gpt-image-2`**, and the series of models **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`** that can be accessed through the same interface. They can all generate high-quality images based on text descriptions. This document mainly introduces the usage process of the OpenAI Images Generations API, allowing us to easily utilize the image generation capabilities of the OpenAI series. ## Application Process To use the OpenAI Images Generations API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page inviting you to register and log in, and after completion, you will be automatically returned to the current page. **One API Token can call all services on the platform without needing to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete documentation: [OpenAI Images Generations API →](https://platform.acedata.cloud/documents/openai-images-generations) ## GPT-Image-2 Model `gpt-image-2` is the new generation image generation model launched by OpenAI, which has significant improvements over `dall-e-3` and `gpt-image-1` in the following aspects: - **Stronger instruction-following ability**: Can accurately understand complex compositions, counting, positional relationships, and other structured instructions. - **Clearer text rendering**: English and numbers in scenarios such as posters, menus, infographics, and logos are almost never garbled. - **Richer style expression**: Natively supports various styles such as cinematic portraits, retro posters, children's illustrations, product photography, and infographics. - **Native multi-aspect ratio + high-resolution support**: Covers 5 aspect ratios (1:1, 4:3, 3:4, 16:9, 9:16) with a total of 3 resolution tiers (1K / 2K / 4K). The calling method is completely consistent with other models; just set the `model` field to `gpt-image-2`. The `url` in the returned result is a permanently hosted image link on `platform.cdn.acedata.cloud`, which can be opened directly in a browser or embedded in a webpage. ### Line Variants (`:official` / `:reverse`) `gpt-image-2` defaults to the standard line. You can explicitly select the line through the model name suffix: - **`gpt-image-2:official`**: Official channel, stable and compliant. Supports true 2K / 4K resolution, **billed per image, with a unit price 2 times that of the default `gpt-image-2`**. If the line is unavailable, it will return an error directly without automatic downgrade. - **`gpt-image-2:reverse`**: Completely equivalent to the default `gpt-image-2`, with a better cost-performance ratio, price unchanged. ### Supported `size` Values `gpt-image-2` only checks the format of `size`; as long as it is not `auto` or an empty string, it needs to match `WIDTHxHEIGHT` (e.g., `1024x1024`, `2048x1152`, `800x600`); any other form will return 400. **All sizes (1K / 2K / 4K / custom) are charged uniformly per image, without additional charges based on size.** Size limitations: Custom sizes must meet the criteria of both width and height being multiples of 16, long side ≤ 3840, total pixel count ≤ 8,294,400; exceeding the range will return a 4xx error. | Ratio | 1K Recommended | 2K Recommended | 4K Recommended | | ---- | ------------- | ------------- | ------------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > When explicitly passing `size: "auto"`, the platform will plan the canvas in a continuous aspect ratio space and determine based on the following priorities: explicit pixels or ratios in the prompt, naming standards (paper / print / platform ad / advertisement / device / photography / film), medium conventions, and finally composition inference. Therefore, in addition to common ratios like `1:1`, `4:5`, `9:16`, `21:9`, it can also retain non-predefined ratios like `1.91:1`, `1.85:1`, `2.39:1`, ISO paper `1:√2`; the final size will be automatically adjusted to the service-supported multiples of 16 and pixel budget. If automatic judgment is unavailable, it will revert to the model's default aspect ratio without blocking generation. Omitting the `size` field will directly use the model's default aspect ratio; if strict pixel requirements are needed, it is still recommended to directly pass `WIDTHxHEIGHT`. > Outputs under the 1K tier do not guarantee strict pixel alignment—if you pass `1024x1024`, you might receive `1254x1254`, maintaining the same ratio. If you pass it back as `size`, the billing remains unchanged. > A single call for 4K usually takes 4–8 minutes; it is recommended to use it with the `callback_url` asynchronous callback mentioned later. > **About the `n` Parameter** > `gpt-image-2` supports `n > 1` (values 1–10): a single request can return and bill for the corresponding number of images. To ensure that multiple results have differences, it is recommended to pass different `prompts` or `seeds` simultaneously. This also applies to `gpt-image-1` / `gpt-image-1.5`, as well as the `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` series; `dall-e-3` only supports `n = 1`. Note that `response_format=b64_json` only supports `n=1`; for `n>1`, please use the default URL return. If some images fail to generate, only the successful parts will be returned and billed. Below are several real examples from different perspectives to intuitively feel the capabilities of `gpt-image-2`. ### Scene 1: Cinematic Portrait In the prompt, you can use film terminology (35mm film, shallow depth of field, neon light, etc.) to precisely control the atmosphere and texture. Python sample call code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The returned result is as follows: ```json { "success": true, "task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3", "created": 1777048800, "data": [ { "revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.", "url": "https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png" } ] } ``` The generated image is shown below:

### Scene 2: Vintage Travel Poster (with Text Rendering) `gpt-image-2` performs stably in typesetting and font rendering, making it very suitable for generating posters, menus, greeting cards, and other designs with text. ```python payload = { "model": "gpt-image-2", "prompt": "A vintage travel poster of the Amalfi Coast, Italy. Stylized art-deco illustration of cliffside lemon-yellow houses cascading down to a turquoise sea, with a small white sailboat in the harbor. Bold typography at the top reads AMALFI and at the bottom ITALIA 1958. Limited color palette: cream, sea-blue, lemon yellow, terracotta. Slight paper-grain texture.", "size": "1024x1536" } ``` The image corresponding to the `url` field in the returned result is as follows:

It can be seen that the model not only accurately restored the visual style of the Art Deco poster, but the title text `AMALFI` and `ITALIA 1958` were also rendered clearly and correctly. ### Scene 3: Complex Composition and Counting The following prompt is used to test the model's adherence to structured instructions such as "quantity" and "position." ```python payload = { "model": "gpt-image-2", "prompt": "A wooden bookshelf consisting of three shelves: On the top shelf, there should be one book. On the second shelf, there should be three books. On the bottom shelf, there should be seven books. Soft warm lighting, photorealistic, cozy library atmosphere.", "size": "1024x1024" } ``` The generated image is as follows:

It can be seen that the number of books on the three shelves (1 / 3 / 7) is completely consistent with the prompt, which is something that was difficult to achieve stably in the `dall-e-3` era. ### Scene 4: Illustration Style (Landscape) By specifying artistic media and emotional keywords, you can guide the model to produce stylized illustrations. ```python payload = { "model": "gpt-image-2", "prompt": "A soft, poetic children's book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.", "size": "1536x1024" } ``` The generated landscape illustration is as follows: ![](https://platform.cdn.acedata.cloud/gpt-image/6cd57e69-d237-4cc1-a666-759a93964a08_0.png) ### Asynchronous and Callback `gpt-image-2` typically requires 60 to 90 seconds for a single call. If you do not wish to maintain a long connection, you can use the `callback_url` asynchronous callback mechanism introduced later in this article. The calling process is completely consistent with other models. ## Nano Banana Series Models The `nano-banana` series is an image generation model based on Gemini, which has been integrated through the same `/openai/images/generations` interface. There is no need to switch endpoints; just change the `model` to any of those in the table below. | Model | Billing (Credits / Time) | Applicable Scenarios | | ---------------------- | --------------------- | ------------------------------------ | | `nano-banana` | 0.14 | General image generation, fastest speed, lowest cost | | `nano-banana-2-lite` | 0.14 | Gemini 3.1 lightweight image model, supports only 1K, low latency | | `nano-banana-2` | 0.28 | Significant improvement in quality and detail | | `nano-banana-pro` | 0.35 | The flagship of the series, best in composition, detail, and text | > **Important: Parameter Support Range** > Nano Banana connects to the OpenAI protocol through an adaptation layer and supports only the following parameters compared to `gpt-image-*`: `model`, `prompt`, `size`, `n`. > - `size` will be mapped to internal `aspect_ratio` as per the table below; unlisted sizes will degrade to `1:1`: > - `1024x1024` / `512x512` / `256x256` → `1:1` > - `1792x1024` → `16:9` > - `1024x1792` → `9:16` > - Does not support parameters such as `quality`, `style`, `response_format`, `background`, `output_format`, etc.; any filled will be ignored. `n > 1` is supported (1–10), and will return and charge for the corresponding number of images. > - The return structure follows the OpenAI format (`data[].url`), but `created` is fixed at `0`, and `b64_json` will not be returned; `revised_prompt` will always equal the original `prompt`. ### Basic Call ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "nano-banana", "prompt": "a small red apple on a white table, photoreal", "size": "1024x1024" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` The returned result is as follows: ```json { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png", "revised_prompt": "a small red apple on a white table, photoreal" } ] } ``` The generated image can be accessed directly through the returned `url` field:

### Upgrade to flagship model `nano-banana-pro` Just change the `model` to `nano-banana-pro`, and the other parameters remain exactly the same: ```python payload = { "model": "nano-banana-pro", "prompt": "abstract painting", "size": "1024x1024" } ``` Return example: ```json { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png", "revised_prompt": "abstract painting" } ] } ```

### Asynchronous Callback The `callback_url` asynchronous callback mechanism is also effective for nano-banana, and the calling process is completely consistent with other models. For details, see the section [Asynchronous Callback](#异步回调). ## Basic Usage Next, you can fill in the corresponding content on the interface, as shown in the figure:

When using this interface for the first time, we need to fill in at least three pieces of content: one is `authorization`, which can be selected directly from the dropdown list. The other parameter is `model`, which is the model category we choose to use from the OpenAI DALL-E official website. Here we mainly have 1 type of model; details can be found in the models we provide. The last parameter is `prompt`, which is the prompt we input to generate the image. You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing.

Python sample calling code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we find the returned result as follows: ```json { "created": 1721626477, "data": [ { "revised_prompt": "A delightful image showcasing a young sea otter, who is born brown, with wide charming eyes. It is delightfully lying on its back, paddling in the calm sea waters. Its dense, velvety fur appears wet and shimmering, capturing the essence of its habitat. The small creature curiously plays with a sea shell with its small paws, looking absolutely innocent and charming in its natural environment.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` The returned result contains multiple fields, described as follows: - `created`, the ID of the image generation for this task, used to uniquely identify this task. - `data`, contains the result information of the image generation. Among them, `data` contains the specific information of the model-generated image, and its `url` is the detailed link to the generated image, as shown in the figure.

## Image Quality Parameter `quality` Next, we will introduce how to set some detailed parameters for the image generation results, among which the image quality parameter `quality` includes two types: the first `standard` indicates generating standard images, and the other `hd` indicates that the created image has finer details and greater consistency. Below, set the image quality parameter to `standard`, with specific settings as shown in the figure:

You can also notice that there is corresponding code generation on the right side; you can copy the code to run directly or click the "Try" button for testing.

Python sample calling code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "quality": "standard" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we find the returned result as follows: ```json { "created": 1721636023, "data": [ { "revised_prompt": "A cute baby sea otter is lying playfully on its back in the water, with its fur looking glossy and soft. One of its tiny paws is reaching out curiously, and it has an expression of pure joy and warmth on its face as it looks up to the sky. Its body is surrounded by bubbles from its playful twirling in the water. A gentle breeze is playing with its fur making it look more charming. The scene portrays the tranquility and charm of marine life.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` The returned results are consistent with the basic usage content, and the generated image with the quality parameter set to `standard` is shown below:

With the same operation as above, simply setting the image quality parameter to `hd` will yield the image shown below:

It can be seen that the image generated with `hd` has finer details and greater consistency than that generated with `standard`. ## Image Size Parameter `size` We can also set the size of the generated image, and we can make the following settings. The image size is set to `1024 * 1024`, with the specific settings shown below:

You can also notice that there is corresponding code generation on the right side, which you can copy and run directly, or you can click the "Try" button to test.

Python sample call code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "size": "1024x1024" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we found that the returned result is as follows: ```json { "created": 1721636652, "data": [ { "revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` The returned result is consistent with the basic usage content, and the generated image with the size of `1024 * 1024` is shown below:

With the same operation as above, simply setting the image size to `1792 * 1024` will yield the image shown below: ![](https://cdn.acedata.cloud/4pilae.png) It can be seen that the image sizes are noticeably different, and more sizes can be set; for detailed information, please refer to our official documentation. ## Image Style Parameter `style` The image style parameter `style` includes two parameters, the first one `vivid` indicates that the generated image is more vivid, while the other `natural` indicates that the generated image is more natural. The image style parameter is set to `vivid`, with the specific settings shown below:

You can also notice that there is corresponding code generation on the right side, which you can copy and run directly, or you can click the "Try" button to test.

Python sample call code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "style": "vivid" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we found that the returned result is as follows: ```json { "created": 1721637086, "data": [ { "revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` The returned result is consistent with the basic usage content, and the generated image with the style parameter set to `vivid` is shown below:

With the same operation as above, simply setting the image style parameter to `natural` will yield the image shown below:

It can be seen that the image generated with `vivid` is more vivid and realistic than that generated with `natural`. ## Image Link Format Parameter `response_format` The last image link format parameter `response_format` also has two types, the first one `b64_json` encodes the image link in Base64, while the other `url` is a regular image link that can be viewed directly. The image link format parameter is set to `url`, with the specific settings shown below:

You can also notice that there is corresponding code generation on the right side, which you can copy and run directly, or you can click the "Try" button to test.

Python sample call code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "response_format": "url" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` After the call, we found the returned result as follows: ```json { "created": 1721637575, "data": [ { "revised_prompt": "A charming depiction of a baby sea otter. The otter is seen resting serenely on its back amidst the gentle, blue ocean waves. The baby otter's fur is an endearing mix of soft greyish brown shades, glinting subtly in the muted sunlight. Its small paws are touching, lifted slightly towards the sky as if playing with an unseen object. Its round, expressive eyes are wide in curiosity, sparking with life and innocence. Use a realistic style to evoke the otter's natural habitat and its adorably fluffy exterior.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` The returned result is consistent with the basic usage content, and we can see that the format parameter of the image link for `url` generates the image link [Image URL](https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02) which can be accessed directly, and the image content is shown below:

With the same operation as above, simply changing the image link format parameter to `b64_json`, we can obtain the result of the Base64 encoded image link, with the specific result shown below: ```json { "created": 1721638071, "data": [ { "b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==", "revised_prompt": "A charming image of a young baby sea otter. The otter is gently floating on a calm blue sea, basking in the warm, golden rays of sunlight streaming down from a clear sky above. The otter's fur is a rich chocolate brown, and it looks incredibly soft and fluffy. The otter's eyes are bright and expressive, filled with childlike curiosity and joy. It has small, pricked ears and a button-like nose which adds to its overall cuteness. In the sea around it, twinkling droplets of water can be seen, pepped up by the sunlight, the sight is certainly a delightful one." } ] } ``` ## Asynchronous Callback Since the OpenAI Images Generations API may take a relatively long time to generate images, if the API does not respond for a long time, the HTTP request will keep the connection open, leading to additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks. The overall process is: when the client initiates a request, an additional `callback_url` field is specified. After the client initiates the API request, the API will immediately return a result containing a `task_id` field information, representing the current task ID. When the task is completed, the generated image result will be sent to the client-specified `callback_url` in the form of a POST JSON, which also includes the `task_id` field, allowing the task result to be associated by ID. Let’s understand how to operate specifically through an example. First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes, we use a public Webhook sample site https://webhook.site/, where you can open the site to get a Webhook URL, as shown in the image: ![](https://cdn.acedata.cloud/cjjfly.png) Copy this URL, and it can be used as a Webhook. The sample here is `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Next, we can set the `callback_url` field to the above Webhook URL, while filling in the corresponding parameters, as shown in the following code: ```python import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` Clicking run, you can find that an immediate result is obtained, as follows: ```json { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` After a moment, we can observe the generated image result on the Webhook URL, with the content as follows: ```json { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "revised_prompt": "A delightful image showcasing a young sea otter...", "url": "https://dalleprodsec.blob.core.windows.net/private/images/..." } ] } } ``` We can see that the result contains a `task_id` field, and the `data` field includes the same image generation result as the synchronous call, allowing the task to be associated through the `task_id` field. ## Error Handling When calling the API, if an error occurs, the API will return the corresponding error code and message. For example: - `400 token_mismatched`: Bad request, possibly due to missing or invalid parameters. - `400 api_not_implemented`: Bad request, possibly due to missing or invalid parameters. - `401 invalid_token`: Unauthorized, invalid or missing authorization token. - `429 too_many_requests`: Too many requests, you have exceeded the rate limit. - `500 api_error`: Internal server error, something went wrong on the server. ### Error Response Example ```json { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusion Through this document, you have learned how to easily use the official OpenAI DALL-E image generation feature with the OpenAI Images Generations API. We hope this document helps you better integrate and use the API. If you have any questions, please feel free to contact our technical support team. --- # Fish TTS API Integration Instructions This interface is based on the [Fish Audio Official TTS API](https://docs.fish.audio/text-to-speech/text-to-speech), with differences only in the authentication method (using the platform token) and asynchronous callback (`callback_url` extension). The request body structure is consistent with the upstream. The address is `POST https://api.acedata.cloud/fish/tts`. ## Application Process To use the Fish TTS API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token for backup. ![](https://cdn.acedata.cloud/5hmkdg.jpg) If you are not logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After completing this, you will be automatically returned to the current page. **One API Token can call all services on the platform, no need to apply separately for each service.** The first application will grant a free quota for a trial experience; when the quota is insufficient, you can recharge the general balance in the [console](https://platform.acedata.cloud/console/coin). > 📘 Complete documentation: [Fish TTS API →](https://platform.acedata.cloud/services/fish) ## Request Headers | Header | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `authorization` | Yes | `Bearer {token}`, where `{token}` is the key applied for on this platform. | | `content-type` | Yes | `application/json`. | | `accept` | No | `application/json`. | | `model` | No | TTS model, optional `s1`, `s2-pro`, or `s2.1-pro`, default is `s2-pro`. `s2.1-pro` is the latest generation, `s2-pro` has strong expressiveness; `s1` is more stable and less prone to deviation with long texts. All three are priced the same. | ## Request Body Fields | Field | Type | Required | Description | | ----------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | Yes | The text to be synthesized, a non-empty string. | | `format` | string | No | Output audio format, optional `mp3` (default), `wav`, `pcm`. Both `wav` and `pcm` return a WAV container. `opus` is not supported and will return `400` if passed. | | `reference_id` | string \| string[] | No | Cloned voice ID (can be created by [Fish Model API](https://platform.acedata.cloud/documents/fish-model) or retrieved in [Fish Model Query](https://platform.acedata.cloud/documents/fish-model-query)). | | `references` | object[] | No | Inline reference samples, structured the same as upstream, each containing `audio` and `text`. One of `reference_id` or `references` must be provided. | | `sample_rate` | integer | No | Sample rate, commonly `16000`, `22050`, `44100`. Default is `44100` for `format=mp3`. | | `mp3_bitrate` | integer | No | MP3 bitrate, optional `64`, `128`, `192`. Only effective for `format=mp3`. | | `prosody` | object | No | Prosody overrides, supports `speed` (speech rate, 1.0 is normal speed) and `volume` (volume gain in dB). For example `{"speed":1.2,"volume":0}`. | | `chunk_length` | integer | No | Upstream chunk length, default determined by upstream. | | `temperature` | number | No | Sampling temperature, range approximately 0.0–1.0. | | `top_p` | number | No | Top-p sampling parameter. | | `latency` | string | No | `normal` or `balanced`, defaults to `normal` automatically filled by this interface (passing an empty string will be rejected by upstream). | | `normalize` | boolean | No | Whether to normalize the text. | | `callback_url` | string | No | Asynchronous callback address, see below "Asynchronous Callback". **This is an extension relative to the official interface**. | > Field naming is completely consistent with upstream. Except for `callback_url`, the meanings and values of other fields refer to the [Fish Official TTS Documentation](https://docs.fish.audio/text-to-speech/text-to-speech). ## Example 1: Minimum Request (`text` + `format=mp3`) ```shell curl -X POST 'https://api.acedata.cloud/fish/tts' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "text": "Hello world.", "format": "mp3" }' ``` Response (actual test): ```json { "audio_url": "https://platform2.cdn.acedata.cloud/fish/e2ffcc06-18da-4a8c-b9aa-9337d0f9ec1d.mp3" } ``` `audio_url` points to the platform CDN, which can be directly downloaded via GET or played in `