Documentação da API

Documentação da API de Plataforma Aberta (v1)

Este documento descreve como usar a API da Plataforma Aberta YinziAI. Os desenvolvedores podem usar a API para criar pedidos, consultar status e muito mais.

Autenticação (Authentication)

Todas as interfaces exigem autenticação via apiKey. O sistema identifica o usuário com base na apiKey, sem depender de Sessão ou Token. Você pode obter sua chave em "Centro de Usuário" -> "API Key".

Dois métodos de autenticação são suportados:

1. Autenticação por Cabeçalho (Recomendado)

   Authorization: Bearer <your_api_key>
   

2. Autenticação por Parâmetro de Consulta

   ?apiKey=<your_api_key>
   

URL Base

https://api.yinziai.com

---

Lista de Interfaces

1. Criar Pedido (Create Order)

Cria um pedido de processamento assíncrono. O sistema gerará automaticamente um número de pedido e o retornará.

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

Parâmetros de Solicitação

Nome do Parâmetro	Tipo	Obrigatório	Descrição
orderType	string	Sim	Tipo de pedido, ver enumeração abaixo
stuff	object	Sim	Informações do material
stuff.pathKey	string	Sim	Endereço do recurso (suporta link HTTP)

Exemplos de Solicitação

Separação de Faixas (track-separation)

Separa o áudio em faixas de vocal e acompanhamento.

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

Extração de Voz (extract-voice)

Extrai a parte vocal do áudio.

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

Extração de Música (extract-music)

Extrai a parte de acompanhamento/música de fundo do áudio.

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

Extração de Texto (extract-text)

Extrai conteúdo de texto de vídeo ou áudio.

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

Exemplo de Resposta

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

Descrição dos Campos de Resposta

Campo	Tipo	Descrição
orderNo	string	Número do pedido, usado para consultas posteriores
orderType	string	Tipo de pedido
orderStatus	string	Status do pedido
payStatus	string	Status do pagamento
messageId	string	ID da mensagem de tarefa

---

2. Consultar Pedido (Query Order)

Consulta o status de processamento e o resultado do pedido. Após a conclusão do processamento, o link de download do resultado será retornado.

Nota: A primeira consulta após a conclusão do pedido deduzirá créditos automaticamente.

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

Parâmetros de Solicitação

Nome do Parâmetro	Tipo	Obrigatório	Descrição
orderNo	string	Sim	Número do pedido

Exemplo de Solicitação

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

Exemplo de Resposta (Processando)

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

Exemplo de Resposta (Concluído)

{
  "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"
}

Descrição dos Campos de Resposta

Campo	Tipo	Descrição
orderNo	string	Número do pedido
orderType	string	Tipo de pedido
status	string	Status do pedido
cost	number	Créditos consumidos
reason	string	Motivo da falha (apenas em caso de falha)
stuffs	array	Lista de resultados
stuffs[].name	string	Nome do arquivo
stuffs[].business	string	Tipo de negócio (vocals/accompaniment/caption, etc.)
stuffs[].url	string	Link de download (válido por 1 hora)
balance	number	Saldo de créditos disponível do usuário atual

---

3. Análise de Vídeo Curto (Short Video Analyze)

Análise em tempo real de links de compartilhamento de vídeos curtos para obter informações de vídeo e endereços de download sem marca d'água.

Nota: Esta interface é uma interface em tempo real, que deduzirá créditos imediatamente e retornará o resultado.

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

Parâmetros de Solicitação

Nome do Parâmetro	Tipo	Obrigatório	Descrição
link	string	Sim	Link de compartilhamento de vídeo curto

Exemplo de Solicitação

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

Exemplo de Resposta

{
  "code": 0,
  "data": {
    "title": "Título do vídeo",
    "author": "Apelido do 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"
}

Descrição dos Campos de Resposta

Campo	Tipo	Descrição
title	string	Título do vídeo
author	string	Apelido do autor
cover	string	Endereço da imagem de capa
videoUrl	string	Endereço de download do vídeo sem marca d'água
musicUrl	string	Endereço de download da música de fundo (se houver)
balance	number	Saldo de créditos disponível do usuário atual

---

Descrição dos Códigos de Erro

Código de Erro	Descrição
0	Sucesso
400	Erro de parâmetro de solicitação
401	Falha na autenticação (API Key inválida ou ausente)
500	Erro interno do servidor

Mensagens de Erro Comuns

Mensagem de Erro	Descrição
API Key is required	API Key é necessária
Invalid API Key	API Key é inválida
pathKey is required	Endereço do recurso é necessário
Order not found	O pedido não existe ou não pertence ao usuário atual
ErrorCode.USER_BLANCE_NOT_ENOUGH	Saldo de créditos insuficiente

---

Apêndice

OrderType (Tipo de Pedido)

Valor	Descrição
track-separation	Separação de faixas (separar vocal e acompanhamento)
extract-voice	Extração de voz
extract-music	Extração de acompanhamento
extract-text	Extração de texto

OrderStatus (Status do Pedido)

Valor	Descrição
pending	Pendente
processing	Processando
finish	Concluído
failed	Falhou
timeout	Tempo esgotado

Plataformas de Vídeo Curto Suportadas

• Douyin
• Kuaishou
• Xiaohongshu
• Weibo
• E outras plataformas de vídeo curto populares