API 参考文档

YaCode 提供完整的 REST API 接口，支持开发者集成 AI 直播功能到自己的应用中。

认证方式

API 密钥认证

所有 API 请求都需要在请求头中包含 API 密钥：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

获取 API 密钥

登录 YaCode 控制台
进入"开发者设置"页面
点击"生成新密钥"按钮
复制并保存生成的密钥

基础信息

API 基础地址

生产环境: https://api.yacode.net/v1
测试环境: https://api-staging.yacode.net/v1

响应格式

所有 API 响应都采用统一的 JSON 格式：

{
  "success": true,
  "data": {
    // 具体数据内容
  },
  "message": "操作成功",
  "timestamp": "2024-01-15T10:30:00Z"
}

错误响应格式：

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "参数无效",
    "details": "商品ID不能为空"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

直播管理 API

创建直播间

创建一个新的 AI 直播间。

POST /streams

请求参数：

{
  "title": "AI主播带货专场",
  "description": "今日特惠商品推荐",
  "platform": "taobao",
  "duration": 240,
  "voice_model": "female-sweet",
  "products": ["prod_001", "prod_002"],
  "script_template": "ecommerce-standard",
  "settings": {
    "auto_reply": true,
    "interaction_frequency": "normal",
    "promotion_emphasis": "high"
  }
}

响应示例：

{
  "success": true,
  "data": {
    "stream_id": "stream_123456",
    "title": "AI主播带货专场",
    "status": "created",
    "rtmp_url": "rtmp://push.yacode.net/live/",
    "stream_key": "sk_abcd1234",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

启动直播

启动指定的直播间。

POST /streams/{stream_id}/start

响应示例：

{
  "success": true,
  "data": {
    "stream_id": "stream_123456",
    "status": "live",
    "started_at": "2024-01-15T10:35:00Z",
    "viewer_count": 0
  }
}

停止直播

停止指定的直播间。

POST /streams/{stream_id}/stop

获取直播状态

获取直播间的实时状态和数据。

GET /streams/{stream_id}/status

响应示例：

{
  "success": true,
  "data": {
    "stream_id": "stream_123456",
    "status": "live",
    "viewer_count": 156,
    "duration": 1800,
    "metrics": {
      "total_viewers": 2340,
      "peak_viewers": 320,
      "messages_count": 1450,
      "products_shown": 12,
      "click_through_rate": 0.08
    }
  }
}

音色管理 API

创建音色模型

使用音频样本创建自定义音色模型。

POST /voices

请求参数（multipart/form-data）：

name: 自定义音色名称
audio_file: 音频文件（3-10秒，WAV/MP3格式）
description: 音色描述（可选）

响应示例：

{
  "success": true,
  "data": {
    "voice_id": "voice_custom_001",
    "name": "自定义音色名称",
    "status": "processing",
    "similarity_score": null,
    "created_at": "2024-01-15T10:30:00Z",
    "estimated_completion": "2024-01-15T10:35:00Z"
  }
}

获取音色列表

获取可用的音色模型列表。

GET /voices

响应示例：

{
  "success": true,
  "data": {
    "voices": [
      {
        "voice_id": "female-sweet",
        "name": "甜美女声",
        "type": "preset",
        "language": "zh-CN",
        "gender": "female",
        "description": "温柔甜美的女性声音"
      },
      {
        "voice_id": "voice_custom_001",
        "name": "自定义音色",
        "type": "custom",
        "language": "zh-CN",
        "status": "ready",
        "similarity_score": 0.95
      }
    ]
  }
}

商品管理 API

添加商品

向直播间添加商品信息。

POST /products

请求参数：

{
  "name": "时尚连衣裙",
  "description": "2024春季新款，舒适透气",
  "price": 299.00,
  "original_price": 399.00,
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "category": "clothing",
  "tags": ["春装", "连衣裙", "时尚"],
  "inventory": 100,
  "platform_product_id": "tb_123456"
}

响应示例：

{
  "success": true,
  "data": {
    "product_id": "prod_123456",
    "name": "时尚连衣裙",
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

获取商品列表

获取商品信息列表。

GET /products?page=1&limit=20&category=clothing

更新商品信息

更新指定商品的信息。

PUT /products/{product_id}

话术管理 API

生成商品话术

为指定商品生成 AI 销售话术。

POST /scripts/generate

请求参数：

{
  "product_id": "prod_123456",
  "style": "enthusiastic",
  "length": "medium",
  "keywords": ["优惠", "限时", "品质"],
  "custom_points": [
    "强调面料舒适性",
    "突出设计时尚感"
  ]
}

响应示例：

{
  "success": true,
  "data": {
    "script_id": "script_789",
    "content": "亲爱的朋友们，给大家推荐这款超级时尚的连衣裙！采用高品质面料，穿着特别舒适透气...",
    "duration": 45,
    "keywords_used": ["优惠", "限时", "品质"],
    "generated_at": "2024-01-15T10:30:00Z"
  }
}

获取话术模板

获取可用的话术模板列表。

GET /scripts/templates

数据分析 API

获取直播数据

获取直播间的详细数据分析。

GET /analytics/streams/{stream_id}?start_date=2024-01-01&end_date=2024-01-15

响应示例：

{
  "success": true,
  "data": {
    "stream_id": "stream_123456",
    "summary": {
      "total_duration": 14400,
      "total_viewers": 5680,
      "peak_viewers": 890,
      "average_viewers": 234,
      "total_messages": 3450,
      "products_showcased": 25,
      "conversion_rate": 0.12
    },
    "hourly_data": [
      {
        "hour": "2024-01-15T10:00:00Z",
        "viewers": 120,
        "messages": 45,
        "orders": 8
      }
    ],
    "top_products": [
      {
        "product_id": "prod_123",
        "name": "时尚连衣裙",
        "views": 1200,
        "clicks": 89,
        "orders": 15
      }
    ]
  }
}

获取商品性能数据

获取商品在直播中的表现数据。

GET /analytics/products/{product_id}

Webhook 事件

YaCode 支持 Webhook 事件推送，在特定事件发生时主动通知您的服务器。

配置 Webhook

POST /webhooks

请求参数：

{
  "url": "https://your-server.com/webhook",
  "events": [
    "stream.started",
    "stream.ended",
    "voice.ready",
    "order.created"
  ],
  "secret": "your_webhook_secret"
}

支持的事件类型

事件类型	描述
`stream.started`	直播开始
`stream.ended`	直播结束
`voice.ready`	音色模型生成完成
`voice.failed`	音色模型生成失败
`order.created`	新订单创建
`error.occurred`	系统错误发生

Webhook 数据格式

{
  "event": "stream.started",
  "data": {
    "stream_id": "stream_123456",
    "started_at": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=abc123..."
}

SDK 示例

JavaScript SDK

import YaCode from '@yacode/js-sdk';

const yacode = new YaCode({
  apiKey: 'your-api-key',
  baseURL: 'https://api.yacode.net/v1'
});

// 创建直播间
const stream = await yacode.streams.create({
  title: 'AI主播带货专场',
  platform: 'taobao',
  voice_model: 'female-sweet',
  products: ['prod_001', 'prod_002']
});

// 启动直播
await yacode.streams.start(stream.stream_id);

// 监听事件
yacode.on('stream.started', (data) => {
  console.log('直播已开始:', data);
});

Python SDK

from yacode import YaCodeClient

client = YaCodeClient(api_key='your-api-key')

# 创建直播间
stream = client.streams.create(
    title='AI主播带货专场',
    platform='taobao',
    voice_model='female-sweet',
    products=['prod_001', 'prod_002']
)

# 启动直播
client.streams.start(stream['stream_id'])

# 获取直播状态
status = client.streams.get_status(stream['stream_id'])
print(f"观众数量: {status['viewer_count']}")

错误代码

错误代码	HTTP状态码	描述
`INVALID_API_KEY`	401	API密钥无效
`INSUFFICIENT_QUOTA`	402	配额不足
`RATE_LIMITED`	429	请求频率超限
`INVALID_PARAMETER`	400	参数无效
`RESOURCE_NOT_FOUND`	404	资源不存在
`INTERNAL_ERROR`	500	服务器内部错误

限制说明

请求频率限制

套餐类型	每分钟请求数	每日请求数
基础版	100	10,000
专业版	1,000	100,000
企业版	无限制	无限制

文件上传限制

音频文件：最大 10MB
图片文件：最大 5MB
支持格式：WAV, MP3, JPEG, PNG

获取帮助

技术支持

开发者文档: https://docs.yacode.net
API 状态页: https://status.yacode.net
技术支持邮箱: dev-support@yacode.net
开发者社区: https://forum.yacode.net

更新日志

v1.2.0 (2024-01-15)

新增商品性能分析 API
增强音色模型训练算法
优化 Webhook 事件推送机制

v1.1.0 (2023-12-20)

新增话术生成 API
支持自定义音色模型
增加数据分析接口

v1.0.0 (2023-11-01)

API 正式发布
基础直播管理功能
预设音色模型支持