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

# 快速开始

> 5 分钟快速接入 SinanCode API

## 第一步：获取 API Key

访问 [API Keys 管理页面](https://sinancode.com/dashboard/keys) 创建您的 API 密钥。

1. 登录您的 SinanCode 账户
2. 进入 Dashboard → API Keys
3. 点击「创建新密钥」
4. 保存生成的 API Key（请妥善保管，仅显示一次）

## 第二步：发起 API 请求

所有 API 请求需要在 HTTP Header 中包含认证信息：

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### 基础请求示例

以下是一个使用 Imagen4 生成图片的完整示例：

```bash theme={null}
curl -X POST https://api.sinancode.com/v1/generate/k/imagen4 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a beautiful sunset over the mountains",
    "aspect_ratio": "16:9",
    "num_images": 1
  }'
```

**响应示例：**

```json theme={null}
{
  "task_id": "01234567-89ab-cdef-0123-456789abcdef"
}
```

## 第三步：查询任务状态

由于 AI 模型生成需要时间，大多数 API 采用异步方式。使用返回的 `task_id` 查询任务状态：

```bash theme={null}
curl -X GET https://api.sinancode.com/v1/tasks/01234567-89ab-cdef-0123-456789abcdef \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**响应示例：**

```json theme={null}
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "status": "completed",
  "result": [
    "https://storage.example.com/generated-image.jpg"
  ]
}
```

### 任务状态说明

* `pending` - 任务排队中
* `processing` - 正在生成
* `completed` - 生成完成
* `failed` - 生成失败

## 常用模型快速参考

### 图片生成模型

#### Imagen 4

* **端点**: `POST /generate/k/imagen4`
* **特点**: Google 最新图片生成模型，质量优秀
* **参数**: `prompt`, `aspect_ratio`, `num_images`, `seed`

#### Midjourney

* **端点**: `POST /generate/k/midjourney-txt2img`
* **特点**: 艺术风格强，适合创意设计
* **参数**: `prompt`, `aspectRatio`, `version`, `stylization`

#### Flux Kontext

* **端点**: `POST /generate/k/flux-kontext`
* **特点**: 支持中文提示词，自动翻译
* **参数**: `prompt`, `aspect_ratio`, `model`, `enable_translation`

### 视频生成模型

#### Sora 2

* **端点**: `POST /generate/k/sora2-text-to-video`
* **特点**: OpenAI 视频生成模型
* **参数**: `prompt`, `aspect_ratio`, `n_frames`

#### Veo 3

* **端点**: `POST /generate/k/veo3-text-to-video`
* **特点**: Google 视频生成模型，支持图生视频
* **参数**: `prompt`, `aspectRatio`, `model`

## 完整代码示例

### Python 示例

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

API_KEY = "your_api_key_here"
BASE_URL = "https://api.sinancode.com/v1"

# 创建任务
response = requests.post(
    f"{BASE_URL}/generate/k/imagen4",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "a futuristic cityscape at sunset",
        "aspect_ratio": "16:9",
        "num_images": 1
    }
)

task_id = response.json()["task_id"]
print(f"任务创建成功，ID: {task_id}")

# 轮询任务状态
while True:
    status_response = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )

    task = status_response.json()
    status = task["status"]

    print(f"任务状态: {status}")

    if status == "completed":
        print(f"生成完成！图片地址: {task['result'][0]}")
        break
    elif status == "failed":
        print(f"生成失败: {task.get('error_msg', 'Unknown error')}")
        break

    time.sleep(2)  # 等待 2 秒后重试
```

### JavaScript/TypeScript 示例

```javascript theme={null}
const API_KEY = "your_api_key_here";
const BASE_URL = "https://api.sinancode.com/v1";

async function generateImage() {
  // 创建任务
  const createResponse = await fetch(`${BASE_URL}/generate/k/imagen4`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt: "a serene mountain landscape",
      aspect_ratio: "16:9",
      num_images: 1
    })
  });

  const { task_id } = await createResponse.json();
  console.log(`任务创建成功，ID: ${task_id}`);

  // 轮询任务状态
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/tasks/${task_id}`, {
      headers: { "Authorization": `Bearer ${API_KEY}` }
    });

    const task = await statusResponse.json();
    console.log(`任务状态: ${task.status}`);

    if (task.status === "completed") {
      console.log(`生成完成！图片地址: ${task.result[0]}`);
      break;
    } else if (task.status === "failed") {
      console.log(`生成失败: ${task.error_msg}`);
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 2000)); // 等待 2 秒
  }
}

generateImage();
```

## 下一步

* 📖 [查看完整 API 文档](/cn/api-reference/introduction) - 了解所有可用模型和参数

## 常见问题

### 如何选择合适的模型？

* **追求质量**: Imagen 4 Ultra, Midjourney v7
* **追求速度**: Imagen 4 Fast, Nano Banana
* **中文提示词**: Flux Kontext, 通义万相
* **视频生成**: Sora 2 Pro, Veo 3

### 请求限制是什么？

每个 API Key 都有速率限制，具体限制取决于您的订阅计划。超出限制时会返回 `429 Too Many Requests` 错误。

需要帮助？访问 [sinancode.com](https://sinancode.com) 联系我们的技术支持团队。