> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Crun 模型 API

> 通过统一 API 平台接入丰富的先进 AI 模型。您可以选择最新的图像生成、视频创作和音频模型，为应用构建 AI 能力。

## 欢迎使用 Crun 模型 API

通过统一 API 探索并集成前沿 AI 模型，覆盖图像生成、视频创作和音频处理等场景。

## 图像模型

面向图像生成、编辑和增强的 AI 模型集合。

<CardGroup cols={2}>
  <Card title="Google" icon="image" href="/zh/models/google/nano-banana-pro">
    Google Gemini 图像系列（Nano Banana），支持高质量图像生成和编辑，具备出色的真实感表现和语义理解能力。
  </Card>

  <Card title="Seedream" icon="image" href="/zh/models/seedream/seedream-5">
    Seedream 5 和 4.x 图像模型系列，支持文生图生成，在细节渲染和风格一致性方面表现出色。
  </Card>

  <Card title="Flux" icon="image" href="/zh/models/flux/flux-2-pro">
    Flux 2、Flux Kontext 和 Flux Pro 图像模型，支持文生图和图生图生成，并提供高级构图控制能力。
  </Card>

  <Card title="Qwen" icon="image" href="/zh/models/qwen/qwen-image-2">
    Qwen-Image 和 Qwen-Image-edit 具备强大的通用图像生成与编辑能力，在文字渲染方面表现尤其突出，特别适合中文文字场景。
  </Card>

  <Card title="OpenAI" icon="image" href="/zh/models/openai/gpt-image-2">
    gpt-image-2 模型支持图像生成与编辑，具备强语义理解能力和高质量输出效果。
  </Card>

  <Card title="Grok Imagine" icon="image" href="/zh/models/grok-imagine/text-to-image">
    支持高质量写实图像生成、文生图以及更具创意的图像创作。
  </Card>
</CardGroup>

## 视频模型

面向文本和图像生成视频、视频编辑与视频转换的先进 AI 模型。

<CardGroup cols={2}>
  <Card title="Bytedance" icon="video" href="/zh/models/seedance/2-0/image-to-video">
    Seedance 2.0 和 Seedance 2.0 Fast 由字节跳动 Seed 团队开发，支持文生视频、图生视频和参考图生视频，可生成 4-15 秒视频，支持音频生成，并具备较强的主体一致性。
  </Card>

  <Card title="Google" icon="video" href="/zh/models/google/veo-3-1-image-to-video">
    Google Veo 是其最强大的视频生成模型系列，原生支持同步音频，可利用 3 张参考图保持一致性，并支持 1080p 输出分辨率。
  </Card>

  <Card title="Wan" icon="video" href="/zh/models/wan/2-6-image-to-video">
    阿里巴巴 Wan 系列 AI 视频生成模型支持从文本、音频、图像或参考片段生成高质量、口型同步的 1080p 视频。
  </Card>

  <Card title="Sora2" icon="video" href="/zh/models/sora2/sora-2-pro">
    Sora 是 OpenAI 最新的生成式媒体前沿模型，可根据自然语言或图像创建细节丰富、动态自然且带音频的视频片段。
  </Card>

  <Card title="Vidu" icon="video" href="/zh/models/vidu/q3-pro/image-to-video">
    Vidu Q 系列视频模型具备强大的图生视频能力，支持从单张图片、首尾帧图片和多张参考图生成视频。
  </Card>

  <Card title="Grok Imagine Video" icon="video" href="/zh/models/grok-imagine/image-to-video">
    Grok Imagine 基于 xAI 的 Aurora 引擎，支持从图像和文本生成 6-30 秒带声音的视频，并提供多种模式以支持更高创意自由度。
  </Card>
</CardGroup>

## 语言模型

兼容 OpenAI 接口的大语言模型，适用于聊天、推理、编程和文本生成。

<CardGroup cols={2}>
  <Card title="OpenAI-Compatible LLM" icon="message" href="/zh/models/llm/quickstart">
    可通过 OpenAI SDK 或任何已支持 `/chat/completions` 的客户端接入 CRUN 语言模型。
  </Card>

  <Card title="Chat Completions API" icon="message" href="/zh/models/llm/chat-completions">
    OpenAI 兼容 `/chat/completions` 接口的完整 API 参考，包含请求参数和流式输出说明。
  </Card>

  <Card title="Responses API" icon="sparkles" href="/zh/models/llm/responses">
    OpenAI 兼容 `/responses` 接口，支持灵活输入、结构化输出、流式输出和工具就绪工作流。
  </Card>

  <Card title="Anthropic Messages API" icon="message" href="/zh/models/llm/messages">
    Anthropic 兼容 `/messages` 接口，适用于 Claude 风格客户端，支持 system prompt、视觉、工具、thinking 和流式输出。
  </Card>
</CardGroup>

## 音频模型

AI 音频处理能力，包括音乐生成、语音合成、语音识别和音频效果处理。

<CardGroup cols={2}>
  <Card title="Qwen3 TTS" icon="waveform-lines" href="/zh/models/qwen/qwen-tts">
    统一的文本转语音演示，提供 Voice、Clone 和 Design 三种强大模式。
  </Card>

  <Card title="Suno音乐 API" icon="music" href="/zh/suno-api/quickstart">
    支持 Suno 多种音乐模型，包括最新的Suno V5模型。
  </Card>
</CardGroup>

## 快速开始

<Steps>
  <Step title="选择模型">
    从上方分类中选择最适合您使用场景的 AI 模型。
  </Step>

  <Step title="获取 API Key">
    访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取您的 API 凭证。
  </Step>

  <Step title="接入接口">
    按照具体模型的文档，将 API 集成到您的应用中。
  </Step>

  <Step title="开始创作">
    通过简单的 API 调用，使用所选 AI 模型开始生成内容。
  </Step>
</Steps>

## 最佳实践

所有模型都遵循一致的 API 结构，便于集成和调用。

### 身份验证

所有 API 请求都需要在请求头中携带 API Key。

```bash theme={null} theme={null}
X-API-KEY: YOUR_API_KEY
```

<Warning>
  请妥善保管您的 API Key。切勿在客户端代码或公开代码仓库中暴露它。
</Warning>

### 创建任务

所有创建任务请求都使用统一的外层结构。不同模型仅 `input` 字段不同。

<Warning>
  只有 HTTP 状态码和业务状态码都为 200 时，才表示请求成功。
</Warning>

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X POST "https://api.crun.ai/api/v1/client/job/CreateTask" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d '{
      "model": "google/veo3-1-t2v",
      "callback_url": "",
      "input": {
        "...": "model-specific fields"
      }
    }'
  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask"

  payload = {
      "model": "google/veo3-1-t2v",
      "callback_url": "https://your.domain/api/v1/callback/task", # 使用回调通知
      # "callback_url": "",
      "input": {
          "...": "model-specific fields"
      }
  }
  headers = {
      "X-API-KEY": API_KEY,
      "Content-Type": "application/json"
  }
  try:
      response = requests.post(CREATE_TASK_URL, json=payload, headers=headers)
      resp_json = response.json()
      # 需要 HTTP 状态码和业务状态码同时为 200，才表示成功
      if response.status_code == 200 and resp_json.get("code") == 200:
          # 成功处理逻辑
          pass
      else:
          # 业务错误处理逻辑
          pass

  except Exception as e:
      print(f"创建任务时发生异常: {str(e)}")
  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const CREATE_TASK_URL = "https://api.crun.ai/api/v1/client/job/CreateTask";

  async function createTask() {
    const payload = {
      model: "google/veo3-1-t2v",
      callback_url: "https://your.domain/callback/task", // 使用回调通知
      // callback_url: "",
      input: {
        "...": "model-specific fields"
      }
    };

    try {
      const response = await axios.post(CREATE_TASK_URL, payload, {
        headers: {
          "X-API-KEY": API_KEY,
          "Content-Type": "application/json"
        }
      });

      const respJson = response.data;

      // 需要 HTTP 状态码和业务状态码同时为 200，才表示成功
      if (response.status === 200 && respJson.code === 200) {
        // 成功处理逻辑
      } else {
        // 业务错误处理逻辑
      }
    } catch (error) {
      console.error(
        "创建任务时发生异常:",
        error.response?.data || error.message
      );
    }
  }

  createTask();
  ```
</CodeGroup>

#### 响应示例

<CodeGroup>
  ```json 200 theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
    	"task_id": "xxxx-xxxx"
    }
  }
  ```

  ```json 4xx theme={null} theme={null}
  {
    "code": 422,
    "message": "Missing Params or Type Error"
  }
  ```

  ```json 5xx theme={null} theme={null}
  {
    "code": 500,
    "message": "Internal Service Error"
  }
  ```
</CodeGroup>

### 轮询任务状态

<Tip>
  建议轮询间隔设置为 15 到 30 秒。生产环境中，建议优先使用 webhook 回调。
</Tip>

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=xxxx-xxxx" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import time
  import requests

  API_KEY = "YOUR_API_KEY"
  GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

  poll_interval = 15

  headers = {
      "X-API-KEY": API_KEY,
      "Content-Type": "application/json"
  }

  params = {
      "task_id": "xxxx-xxxx",
  }

  while True:
      response = requests.get(GET_TASK_STATUS_URL, headers=headers, params=params)
      resp_json = response.json()

      task_status = resp_json["data"]["status"]
      print(f"Task status: {task_status}")

      if task_status == "success":
          # 业务成功处理逻辑
          break
      elif task_status == "failed":
          # 业务失败处理逻辑
          break
      else:
          # 任务状态为 pending 或 running
          time.sleep(poll_interval)
  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo";

  const poll_interval = 15;

  const headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  };

  const params = {
    task_id: "xxxx-xxxx",
  };

  async function pollTaskStatus() {
    while (true) {
      const response = await axios.get(GET_TASK_STATUS_URL, {
        headers,
        params
      });

      const resp_json = response.data;

      const task_status = resp_json.data.status;
      console.log(`Task status: ${task_status}`);

      if (task_status === "success") {
        // 业务成功处理逻辑
        break;
      } else if (task_status === "failed") {
        // 业务失败处理逻辑
        break;
      } else {
        // 任务状态为 pending 或 running
        await new Promise((resolve) => setTimeout(resolve, poll_interval * 1000));
      }
    }
  }

  pollTaskStatus();
  ```
</CodeGroup>

#### 响应示例

<CodeGroup>
  ```json task processing theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
    	"task_id": "3f8e4789-29df-4793-89cc-acb71a1b79d9",
    	"provider": "Google",
    	"model_version": "veo3.1",
    	"status": "running",
    	"param": {
    		"model": "google/veo3-1-t2v",
    		"callback_url": "https://your.domain/api/v1/callback/task",
    		"input": {
    			"...": "model-specific fields"
    		}
    	},
    	"create_at": 1768450365,
    	"result": null,
    	"duration_s": null,
    	"complete_at": null
    }
  }
  ```

  ```json task success theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
    	"task_id": "3f8e4789-29df-4793-89cc-acb71a1b79d9",
    	"provider": "Google",
    	"model_version": "veo3.1",
    	"status": "success",
    	"param": {
    		"model": "google/veo3-1-t2v",
    		"callback_url": "https://your.domain/api/v1/callback/task",
    		"input": {
    			"...": "model-specific fields"
    		}
    	},
    	"create_at": 1768450365,
    	"result": {
    		"cdoe": 200,
    		"message": "generation success",
    		"media_urls": [
    			"..."
    		]
    	},
    	"duration_s": 104,
    	"complete_at": 1768450469
    }
  }
  ```

  ```json task failed theme={null} theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
    	"task_id": "3f8e4789-29df-4793-89cc-acb71a1b79d9",
    	"provider": "Google",
    	"model_version": "veo3.1",
    	"status": "failed",
    	"param": {
    		"model": "google/veo3-1-t2v",
    		"callback_url": "https://your.domain/api/v1/callback/task",
    		"input": {
    			"...": "model-specific fields"
    		}
    	},
    	"create_at": 1768450365,
    	"result": {
    		"cdoe": 501,
    		"message": "error message"
    	},
    	"duration_s": 104,
    	"complete_at": 1768450469
    }
  }
  ```
</CodeGroup>

<Tip>
  1. 任务状态由响应 `data` 对象中的 `status` 字段决定。
  2. 当 `status` 为 `success` 时，可从 `data.result.media_urls` 获取生成的媒体 URL。
  3. 当 `status` 为 `failed` 时，请查看 `data.result` 中的错误码和错误信息。
</Tip>

### 回调通知

虽然接口支持轮询，但生产系统中强烈建议使用 webhook 回调。创建任务时如果提供 `callback_url`，请确保：

* 回调地址可通过公网 HTTPS 访问。
* 接口能够快速响应，建议响应时间小于 3 秒，以避免重试。
* 成功接收通知后返回 HTTP 200 状态码。
* 接口具备幂等性。回调通知可能会被投递多次。

回调 payload 与任务状态查询 API 使用相同结构，因此可以复用同一套解析逻辑。

<Tip>
  当任务状态发生变化时，我们会通过 POST 请求向您通知结果。
  payload 结构与任务状态查询返回的 `data` 对象一致。
  生产环境中，我们强烈建议使用回调通知获取任务结果。
</Tip>

## 积分与定价

不同模型会根据计算资源需求消耗不同数量的积分：

* **图像模型**：通常每次生成消耗 10-50 积分
* **视频模型**：通常每次生成消耗 100-500 积分
* **语言模型**：按 token 用量计费

请访问 [pricing](https://crun.ai/zh/zh/pricing) 页面查看各模型的详细价格。

查询剩余积分：

<CodeGroup>
  ```curl cURL theme={null} theme={null}
  curl -X POST "https://api.crun.ai/api/v1/client/account/balance" \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"
  GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance"

  headers = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}
  response = requests.post(GET_BALANCE_URL, headers=headers)

  print(response.json())
  ```

  ```javascript Node.js theme={null} theme={null}
  import axios from "axios";

  const API_KEY = "YOUR_API_KEY";
  const GET_BALANCE_URL = "https://api.crun.ai/api/v1/client/account/balance";

  const headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  };

  axios
    .post(GET_BALANCE_URL, null, { headers })
    .then((response) => {
      console.log(response.data);
    })
    .catch((error) => {
      console.error(error.response?.data || error.message);
    });
  ```
</CodeGroup>

## 支持

需要帮助选择合适的模型，或需要协助接入 API？

* 邮箱：[support@crun.ai](mailto:support@crun.ai)
* 文档：请在导航中查看各模型的专属接入指南