Documentación de la API

Documentación de la API de Plataforma Abierta (v1)

Este documento describe cómo utilizar la API de la Plataforma Abierta YinziAI. Los desarrolladores pueden utilizar la API para crear pedidos, consultar estados y más.

Autenticación (Authentication)

Todas las interfaces requieren autenticación a través de apiKey. El sistema identifica al usuario en función de la apiKey, sin depender de sesiones o tokens. Puede obtener su clave en "Centro de Usuario" -> "API Key".

Se admiten dos métodos de autenticación:

1. Autenticación por Encabezado (Recomendado)

   Authorization: Bearer <your_api_key>
   

2. Autenticación por Parámetro de Consulta

   ?apiKey=<your_api_key>
   

URL Base

https://api.yinziai.com

---

Lista de Interfaces

1. Crear Pedido (Create Order)

Crea un pedido de procesamiento asíncrono. El sistema generará automáticamente un número de pedido y lo devolverá.

• URL: /api/open/v1/order/create
• Method: POST
• Content-Type: application/json

Parámetros de Solicitud

Nombre del Parámetro	Tipo	Requerido	Descripción
orderType	string	Sí	Tipo de pedido, ver enumeración abajo
stuff	object	Sí	Información del material
stuff.pathKey	string	Sí	Dirección del recurso (admite enlace HTTP)

Ejemplos de Solicitud

Separación de Pistas (track-separation)

Separa el audio en pistas de voz y acompañamiento.

{
  "orderType": "track-separation",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

Extracción de Voz (extract-voice)

Extrae la parte vocal del audio.

{
  "orderType": "extract-voice",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

Extracción de Música (extract-music)

Extrae la parte de acompañamiento/música de fondo del audio.

{
  "orderType": "extract-music",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

Extracción de Texto (extract-text)

Extrae contenido de texto de video o audio.

{
  "orderType": "extract-text",
  "stuff": {
    "pathKey": "https://example.com/video.mp4"
  }
}

Ejemplo de Respuesta

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "orderStatus": "processing",
    "payStatus": "waiting",
    "messageId": "task-id-123"
  },
  "msg": "success"
}

Descripción de Campos de Respuesta

Campo	Tipo	Descripción
orderNo	string	Número de pedido, utilizado para consultas posteriores
orderType	string	Tipo de pedido
orderStatus	string	Estado del pedido
payStatus	string	Estado del pago
messageId	string	ID de mensaje de tarea

---

2. Consultar Pedido (Query Order)

Consulta el estado de procesamiento y el resultado del pedido. Una vez completado el procesamiento, se devolverá el enlace de descarga del resultado.

Nota: La primera consulta después de completar el pedido deducirá créditos automáticamente.

• URL: /api/open/v1/order/query
• Method: GET

Parámetros de Solicitud

Nombre del Parámetro	Tipo	Requerido	Descripción
orderNo	string	Sí	Número de pedido

Ejemplo de Solicitud

GET /api/open/v1/order/query?orderNo=abc123XYZ789defGHI
Authorization: Bearer <your_api_key>

Ejemplo de Respuesta (Procesando)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "processing",
    "cost": 0,
    "reason": null,
    "stuffs": [],
    "balance": 1000
  },
  "msg": "success"
}

Ejemplo de Respuesta (Terminado)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "finish",
    "cost": 10,
    "reason": null,
    "stuffs": [
      {
        "name": "vocals.mp3",
        "business": "vocals",
        "url": "https://cdn.example.com/result/vocals.mp3"
      },
      {
        "name": "accompaniment.mp3",
        "business": "accompaniment",
        "url": "https://cdn.example.com/result/accompaniment.mp3"
      }
    ],
    "balance": 990
  },
  "msg": "success"
}

Descripción de Campos de Respuesta

Campo	Tipo	Descripción
orderNo	string	Número de pedido
orderType	string	Tipo de pedido
status	string	Estado del pedido
cost	number	Créditos consumidos
reason	string	Razón del fallo (solo cuando falla)
stuffs	array	Lista de resultados
stuffs[].name	string	Nombre del archivo
stuffs[].business	string	Tipo de negocio (vocals/accompaniment/caption, etc.)
stuffs[].url	string	Enlace de descarga (válido por 1 hora)
balance	number	Saldo de créditos disponible del usuario actual

---

3. Análisis de Video Corto (Short Video Analyze)

Análisis en tiempo real de enlaces compartidos de videos cortos para obtener información del video y direcciones de descarga sin marca de agua.

Nota: Esta interfaz es una interfaz en tiempo real, que deducirá créditos inmediatamente y devolverá el resultado.

• URL: /api/open/v1/short-video/analyze
• Method: POST
• Content-Type: application/json

Parámetros de Solicitud

Nombre del Parámetro	Tipo	Requerido	Descripción
link	string	Sí	Enlace compartido de video corto

Ejemplo de Solicitud

{
  "link": "https://v.douyin.com/ixxxxxx/"
}

Ejemplo de Respuesta

{
  "code": 0,
  "data": {
    "title": "Título del video",
    "author": "Apodo del autor",
    "cover": "https://cdn.example.com/cover.jpg",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "musicUrl": "https://cdn.example.com/music.mp3",
    "balance": 990
  },
  "msg": "success"
}

Descripción de Campos de Respuesta

Campo	Tipo	Descripción
title	string	Título del video
author	string	Apodo del autor
cover	string	Dirección de la imagen de portada
videoUrl	string	Dirección de descarga del video sin marca de agua
musicUrl	string	Dirección de descarga de la música de fondo (si la hay)
balance	number	Saldo de créditos disponible del usuario actual

---

Descripción de Códigos de Error

Código de Error	Descripción
0	Éxito
400	Error de parámetro de solicitud
401	Autenticación fallida (API Key inválida o faltante)
500	Error interno del servidor

Mensajes de Error Comunes

Mensaje de Error	Descripción
API Key is required	Se requiere API Key
Invalid API Key	API Key inválida
pathKey is required	Se requiere dirección del recurso
Order not found	El pedido no existe o no pertenece al usuario actual
ErrorCode.USER_BLANCE_NOT_ENOUGH	Saldo de créditos insuficiente

---

Apéndice

OrderType (Tipo de Pedido)

Valor	Descripción
track-separation	Separación de pistas (separar voz y acompañamiento)
extract-voice	Extracción de voz
extract-music	Extracción de acompañamiento
extract-text	Extracción de texto

OrderStatus (Estado del Pedido)

Valor	Descripción
pending	Pendiente
processing	Procesando
finish	Finalizado
failed	Fallido
timeout	Tiempo de espera agotado

Plataformas de Video Corto Soportadas

• Douyin
• Kuaishou
• Xiaohongshu
• Weibo
• Y otras plataformas de video corto populares