Documentazione API

Documentazione API Open Platform (v1)

Viene descritto come utilizzare l'API YinziAI Open Platform. Gli sviluppatori possono utilizzare l'API per creare ordini, interrogare lo stato e altro ancora.

Autenticazione (Authentication)

Tutte le interfacce richiedono l'autenticazione tramite apiKey. Il sistema identifica l'utente in base alla apiKey, senza fare affidamento su sessioni o token. Puoi ottenere la tua chiave in "Centro Utente" -> "API Key".

Sono supportati due metodi di autenticazione:

1. Autenticazione tramite Header (Consigliato)

   Authorization: Bearer <your_api_key>
   

2. Autenticazione tramite Parametro di Query

   ?apiKey=<your_api_key>
   

URL Base

https://api.yinziai.com

---

Elenco Interfacce

1. Crea Ordine (Create Order)

Crea un ordine di elaborazione asincrona. Il sistema genererà automaticamente un numero d'ordine e lo restituirà.

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

Parametri Richiesta

Nome Parametro	Tipo	Obbligatorio	Descrizione
orderType	string	Sì	Tipo ordine, vedi elenco sotto
stuff	object	Sì	Informazioni materiale
stuff.pathKey	string	Sì	Indirizzo risorsa (supporta link HTTP)

Esempi Richiesta

Separazione Tracce (track-separation)

Separa l'audio in tracce vocali e di accompagnamento.

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

Estrazione Voce (extract-voice)

Estrae la parte vocale dall'audio.

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

Estrazione Musica (extract-music)

Estrae la parte di accompagnamento/musica di sottofondo dall'audio.

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

Estrazione Testo (extract-text)

Estrae il contenuto testuale da video o audio.

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

Esempio Risposta

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

Descrizione Campi Risposta

Campo	Tipo	Descrizione
orderNo	string	Numero ordine, usato per query successive
orderType	string	Tipo ordine
orderStatus	string	Stato ordine
payStatus	string	Stato pagamento
messageId	string	ID messaggio attività

---

2. Interroga Ordine (Query Order)

Interroga lo stato di elaborazione e il risultato dell'ordine. Dopo il completamento dell'elaborazione, verrà restituito il link per il download del risultato.

Nota: La prima query dopo il completamento dell'ordine dedurrà automaticamente crediti.

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

Parametri Richiesta

Nome Parametro	Tipo	Obbligatorio	Descrizione
orderNo	string	Sì	Numero ordine

Esempio Richiesta

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

Esempio Risposta (In Elaborazione)

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

Esempio Risposta (Terminato)

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

Descrizione Campi Risposta

Campo	Tipo	Descrizione
orderNo	string	Numero ordine
orderType	string	Tipo ordine
status	string	Stato ordine
cost	number	Crediti consumati
reason	string	Motivo fallimento (solo in caso di fallimento)
stuffs	array	Elenco risultati
stuffs[].name	string	Nome file
stuffs[].business	string	Tipo attività (vocals/accompaniment/caption, ecc.)
stuffs[].url	string	Link download (valido per 1 ora)
balance	number	Saldo crediti disponibile dell'utente corrente

---

3. Analisi Video Breve (Short Video Analyze)

Analisi in tempo reale di link di condivisione di video brevi per ottenere informazioni video e indirizzi di download senza filigrana.

Nota: Questa interfaccia è un'interfaccia in tempo reale, che dedurrà immediatamente crediti e restituirà il risultato.

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

Parametri Richiesta

Nome Parametro	Tipo	Obbligatorio	Descrizione
link	string	Sì	Link condivisione video breve

Esempio Richiesta

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

Esempio Risposta

{
  "code": 0,
  "data": {
    "title": "Titolo video",
    "author": "Nickname autore",
    "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"
}

Descrizione Campi Risposta

Campo	Tipo	Descrizione
title	string	Titolo video
author	string	Nickname autore
cover	string	Indirizzo immagine copertina
videoUrl	string	Indirizzo download video senza filigrana
musicUrl	string	Indirizzo download musica di sottofondo (se presente)
balance	number	Saldo crediti disponibile dell'utente corrente

---

Descrizione Codici Errore

Codice Errore	Descrizione
0	Successo
400	Errore parametri richiesta
401	Autenticazione fallita (API Key non valida o mancante)
500	Errore interno server

Messaggi Errore Comuni

Messaggio Errore	Descrizione
API Key is required	API Key richiesta
Invalid API Key	API Key non valida
pathKey is required	Indirizzo risorsa richiesto
Order not found	Ordine non esistente o non appartenente all'utente corrente
ErrorCode.USER_BLANCE_NOT_ENOUGH	Saldo crediti insufficiente

---

Appendice

OrderType (Tipo Ordine)

Valore	Descrizione
track-separation	Separazione tracce (separare voce e accompagnamento)
extract-voice	Estrazione voce
extract-music	Estrazione accompagnamento
extract-text	Estrazione testo

OrderStatus (Stato Ordine)

Valore	Descrizione
pending	In attesa
processing	In elaborazione
finish	Completato
failed	Fallito
timeout	Tempo scaduto

Piattaforme Video Brevi Supportate

• Douyin
• Kuaishou
• Xiaohongshu
• Weibo
• E altre piattaforme video brevi mainstream