Référence API

v4 · Intégration tierce

— Auth —

— Tâches —

— Téléversements —

— Dossiers —

— Utilisateur —

— Notifications —

— Paiement —

Documentation API

API REST pour la transcription audio et vidéo. Les clients payants authentifient les intégrations tierces avec une clé API créée dans les paramètres du compte.

URL de base

https://scribe.uustudio.cc

Authentification

Les intégrations tierces doivent envoyer une clé API d'un compte payant dans l'en-tête Authorization.

En-tête Authorization

Authorization: Bearer {token}

Créez et révoquez les clés depuis la page Clés API des paramètres. Les points d'authentification de l'app sont réservés aux clients officiels.

Réponses d erreur

Toutes les erreurs renvoient un corps JSON avec un champ message .

Erreur standard

{
    "message": "Description of the error"
}

Erreur de validation (422)

{
    "message": "The name field is required.",
    "errors": {
        "name": ["The name field is required."]
    }
}

Statut	Description
401	Non authentifié (token manquant ou invalide)
403	Interdit ou limite du plan dépassée
404	Ressource non trouvée
422	Échec de la validation
429	Limite de débit ou trop de tâches simultanées
500	Erreur interne du serveur

Limites de débit

Les points de terminaison API authentifiés sont limités à 10 requêtes par minute et par token.

Limites d utilisation

Disponibilité de l'API

L'API REST tierce n'est pas disponible avec l'offre gratuite. Passez à Pro ou Max, ou achetez un forfait à l'usage, pour créer et utiliser des clés API.

Taille maximale de fichier: 2 Go
Tâches simultanées: Max 3
Nouveaux essais max par tâche: 3

Comparaison des offres payantes

Caractéristique	Pay as you go	Pro	Max
Téléversements quotidiens	Illimité	Illimité	Illimité
Formats d export	Tous	Tous	Tous
Priorité des tâches	Moyenne	Moyenne	Haute

Flux de travail

Téléverser un fichier audio/vidéo

POST /api/uploads/sign → Obtenir upload_id et informations de partie
PUT {presigned_url} → Téléverser chaque partie vers le stockage
POST /api/uploads/complete → Terminer le téléversement, auto-créer la tâche
GET /api/tasks/{id} → Vérifier le statut (pending -> scribing -> finished)
GET /api/tasks/{id}/download/srt → Exporter (optionnel)

Créer une tâche manuellement

POST /api/tasks → Créer avec disk, path, name
GET /api/tasks/{id} → Vérifier le statut
GET /api/tasks/{id} → Obtenir segments, summary, mindmap

Auth

POST /api/login

Authentifiez-vous avec e-mail et mot de passe. Renvoie un token Sanctum.

Corps de la requête

Champ	Type	Requis	Description
email	string	Yes	E-mail de l'utilisateur (max 255)
password	string	Yes	Mot de passe de l utilisateur

Réponse 200

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

Limité à 5 tentatives par minute par e-mail.

POST /api/register

Créez un nouveau compte. Renvoie un token Sanctum.

Corps de la requête

Champ	Type	Requis	Description
name	string	Yes	Nom d'affichage (max 255)
email	string	Yes	E-mail unique (max 255)
password	string	Yes	Doit être confirmé
password_confirmation	string	Yes	Confirmation du mot de passe

Réponse 201

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

POST /api/auth/social-login

Authentifiez-vous via Google OAuth. Crée un compte s il n existe pas.

Corps de la requête

Champ	Type	Requis	Description
provider	string	Yes	`google` fournisseurs pris en charge
code	string	Yes	Code d autorisation OAuth

Réponse 200

{
    "token": "1|abc123...",
    "user": {
        "id": 1,
        "name": "Zhang San",
        "email": "[email protected]"
    }
}

POST /api/logout

Révoque le token d accès actuel.

Réponse 204

Ne renvoie pas de corps.

Tâches

POST /api/tasks

Crée une tâche de transcription. Max 3 tâches simultanées par utilisateur.

Corps de la requête

Champ	Type	Requis	Description
disk	string	Yes	`r2` / `remote` / `youtube` Identifiant de la source de stockage
name	string	Yes	Nom de la tâche (max 255)
path	string	Yes	Chemin du fichier ou URL source
file	string	No	Nom de fichier original (max 255)
size	integer	No	Taille du fichier en octets
duration	integer	No	Durée en secondes
cost	integer	No	Coût en secondes
segments	array	No	Segments de transcription
speaker_diarization	boolean	Non	app.tasks.speaker_diarization_api_description

Réponse 201

{
    "id": 1,
    "name": "Meeting Recording",
    "status": "pending",
    "speaker_diarization": true,
    "created_at": "2026-03-02T10:30:00+08:00"
}

Erreurs

Statut	Description
403	Les utilisateurs gratuits ne peuvent pas soumettre de liens YouTube via l API.
429	Maximum de 3 tâches simultanées atteint

GET /api/tasks/{id}

Obtenez les détails complets de la tâche, y compris les résultats de transcription.

Réponse

{
    "id": 1,
    "name": "Meeting Recording",
    "file": "meeting.mp3",
    "path": "2026-03-02/01HQX...mp3",
    "disk": "r2",
    "size": 50545869,
    "duration": 1965,
    "cost": 33,
    "status": "finished",
    "attempts": 1,
    "quality": 3,
    "created_at": "2026-03-02T10:30:00+08:00",
    "updated_at": "2026-03-02T10:45:00+08:00",
    "summary": "The meeting discussed three topics...",
    "mindmap": "# Topic\n## Sub-topic 1",
    "folder": "Work",
    "tags": ["Work"],
    "url": "https://youtube.com/watch?v=...",
    "segments": [
        {
            "id": 1,
            "start": 0,
            "end": 5000,
            "speaker": "Speaker 1",
            "tokens": ["Okay", "so let's", "begin"],
            "text": "Okay, so let's begin..."
        }
    ],
    "export": {
        "allowed_formats": ["txt", "srt", "vtt", "csv", "pdf", "docx"],
        "heavy_formats": ["pdf", "docx"],
        "version": "20260302104500"
    }
}

Champs de réponse

Champ	Type	Description
disk	string\|null	Disque de stockage : r2 / remote / youtube
size	int\|null	Taille du fichier en octets
cost	int\|null	Coût en secondes
attempts	int	Nombre de tentatives
quality	int\|null	Score de qualité (0-5)
summary	string\|null	Résumé généré par IA
mindmap	string\|null	Carte mentale générée par IA
folder	string\|null	Nom de la première étiquette (dossier)
tags	array	Tous les noms d étiquettes
url	string\|null	URL source (pour les tâches YouTube)
segments	array\|null	Segments de transcription
segments[].start	int	Temps de début (ms)
segments[].end	int	Temps de fin (ms)
segments[].text	string	Texte du segment
segments[].speaker	string\|null	Identifiant du locuteur
segments[].tokens	array\|null	Tableau de jetons de mots
export	object	Métadonnées d export (allowed_formats, heavy_formats, version)

GET /api/tasks

Paramètres de requête

Paramètre	Type	Par défaut	Description
status	string	all	Filtrer par statut
search	string	—	Rechercher par nom
folder	string	—	Filtrer par dossier (ou `Uncategorized`)
page	int	1	Numéro de page
per_page	int	25	Éléments par page (max 100)

Réponse

{
    "data": [
        {
            "id": 1,
            "name": "Meeting Recording",
            "file": "meeting.mp3",
            "disk": "r2",
            "size": 50545869,
            "duration": 1965,
            "cost": 33,
            "status": "finished",
            "attempts": 1,
            "quality": 3,
            "folder": "Work",
            "created_at": "2026-03-02T10:30:00+08:00"
        }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
}

PATCH /api/tasks/{id}/retry

Réessayer une tâche échouée. Définit le statut à pending (R2) ou waiting (remote/YouTube). Max 3 essais.

Réponse 200

{
    "id": 1,
    "status": "pending",
    "attempts": 2
}

GET /api/tasks/{id}/download/{format}

Exporter la transcription. Les formats légers renvoient le fichier directement. Les formats lourds (pdf/docx) peuvent renvoyer 202 pendant le traitement.

Paramètres de chemin

Paramètre	Description
format	`txt` / `srt` / `vtt` / `csv` / `pdf` / `docx`

Réponses

200 - Fichier prêt (formats légers)

Renvoie un fichier binaire.

200 - Fichier prêt (formats lourds, requête JSON)

{
    "status": "ready",
    "url": "https://scribe.uustudio.cc/api/tasks/1/download/pdf"
}

202 - Traitement du format lourd

{
    "status": "processing",
    "message": "Your export is being generated. Please try again shortly."
}

GET /api/tasks/{id}/audio

Transmettre le fichier audio ou vidéo original directement depuis le stockage (R2 uniquement).

Réponse

200 - Flux binaire du fichier audio ou vidéo. Renvoie 404 si le fichier est manquant ou non stocké sur le disque R2.

GET /api/tasks/{id}/refresh-summary

Actualiser et renvoyer le résumé et la carte mentale générés par IA les plus récents.

Réponse

{
    "summary": "The meeting discussed three topics...",
    "mindmap": "# Topic\n## Sub-topic 1"
}

PATCH /api/tasks/{id}

Mettre à jour les champs de la tâche. Tous les champs sont optionnels.

Corps de la requête

Champ	Type	Description
name	string	Nouveau nom (max 255)
folder	string\|null	Nom du dossier (null retire la tâche d un dossier)
duration	integer	Durée en secondes
cost	integer	Coût en secondes
segments	array	Tableau complet des segments à remplacer
text	string	Texte complet de la transcription
quality	integer	Score de qualité (0-5)
index	integer	Index d'ordre de la tâche

Réponse 200

Renvoie l objet de tâche complet (identique à Détail de la tâche).

DELETE /api/tasks/{id}

Response 200

{
    "message": "Task deleted successfully"
}

DELETE /api/tasks/bulk

Supprimer plusieurs tâches à la fois. Seules les tâches de l utilisateur authentifié seront supprimées. Les IDs n appartenant pas à l utilisateur sont ignorés.

Corps de la requête

Champ	Type	Requis	Description
ids	array	Yes	Tableau d IDs de tâches à supprimer (min 1)

Réponse 200

{
    "message": "2 task(s) deleted successfully",
    "deleted_count": 2
}

PATCH /api/tasks/bulk/move

Déplacer plusieurs tâches vers un dossier à la fois. Seules les tâches de l utilisateur authentifié seront déplacées.

Corps de la requête

Champ	Type	Requis	Description
ids	array	Yes	Tableau d IDs de tâches à déplacer (min 1)
folder	string	Yes	Nom du dossier de destination (max 255)

Réponse 200

{
    "message": "2 task(s) moved to Work",
    "moved_count": 2
}

Téléversements

Téléversement multipart

POST /api/uploads/sign

Corps de la requête

Champ	Type	Requis	Description
file	string	Yes	Nom de fichier (doit utiliser un format pris en charge)
content_type	string	Yes	Type MIME (doit correspondre à l extension du fichier)
size	integer	Yes	Taille du fichier en octets (max 2 147 483 648 / 2 Go)
duration	integer	No	Durée de l'audio en secondes

Réponse

{
    "path": "2026-03-02/01HQX...mp3",
    "upload_id": "abc123",
    "part_size": 5242880,
    "part_count": 10,
    "expires_at": "2026-03-02T10:40:00+08:00"
}

POST /api/uploads/sign-part

Corps de la requête

Champ	Type	Requis	Description
path	string	Yes	Chemin de téléversement (max 2048)
upload_id	string	Yes	ID de téléversement (max 2048)
part_number	integer	Yes	Numéro de partie (1-10000)

Réponse

{
    "url": "https://storage.example.com/...?X-Amz-...",
    "headers": {
        "Content-Type": "audio/mpeg"
    }
}

Utilisez PUT avec l URL et les en-têtes retournés pour téléverser la partie.

POST /api/uploads/complete

Compléter un téléversement multipart. Cela crée automatiquement une tâche et renvoie 403 lorsque l'API est indisponible ou qu'une limite de l'offre est dépassée.

Corps de la requête

Champ	Type	Requis	Description
path	string	Yes	Chemin de téléversement (max 2048)
upload_id	string	Yes	ID de téléversement (max 2048)
original_name	string	Yes	Nom de fichier original (doit utiliser un format pris en charge)
content_type	string	Yes	Type MIME (doit correspondre à l extension du fichier)
size	integer	Yes	Taille du fichier en octets (max 2 Go)
name	string	No	Nom de la tâche (par défaut le nom de fichier sans extension)
duration	integer	No	Durée en secondes (min 1)
speaker_diarization	boolean	Non	app.tasks.speaker_diarization_api_description

Réponse 201

{
    "message": "File uploaded to the upload server successfully.",
    "task": {
        "id": 1,
        "name": "meeting",
        "path": "2026-03-02/01HQX...mp3",
        "size": 50545869,
        "status": "pending",
        "speaker_diarization": true
    }
}

POST /api/uploads/abort

Corps de la requête

Champ	Type	Requis	Description
path	string	Yes	Chemin de téléversement (max 2048)
upload_id	string	Yes	ID de téléversement (max 2048)

Réponse

{
    "message": "Multipart upload cancelled successfully."
}

Dossiers

Basé sur les étiquettes

GET /api/folders

Liste tous les dossiers avec les nombres de tâches.

Réponse

{
    "folders": [
        {"id": 1, "name": "Work", "count": 5},
        {"id": 2, "name": "Personal", "count": 3}
    ],
    "uncategorized_count": 2,
    "total_count": 10
}

POST /api/folders

Corps de la requête

Champ	Type	Requis	Description
name	string	Yes	Nom du dossier (max 14 caractères / 7 caractères chinois, unique par utilisateur)

Réponse 201

{
    "id": 1,
    "name": "Work"
}

PATCH /api/folders/{name}

Corps de la requête

Champ	Type	Requis	Description
name	string	Yes	Nouveau nom du dossier (mêmes contraintes que la création)

Réponse 200

{
    "id": 1,
    "name": "New Name"
}

DELETE /api/folders/{name}

Response 200

{
    "message": "Folder deleted successfully"
}

Utilisateur

GET /api/user

Réponse

{
    "id": 1,
    "name": "Zhang San",
    "email": "[email protected]",
    "avatar": "https://...",
    "balance": {
        "used_seconds": 9000,
        "remaining_seconds": 36000,
        "allowance_remaining_seconds": 30000,
        "top_up_remaining_seconds": 6000,
        "total_seconds": 45000,
        "usage_percent": 20
    },
    "subscription": {
        "plan": "year",
        "plan_key": "max_yearly",
        "tier": "max",
        "billing_interval": "yearly",
        "active": true,
        "access_tier": "max"
    },
    "queue": {
        "pending_count": 1,
        "running_count": 1,
        "failed_count": 0
    }
}

Champs de solde

Champ	Type	Description
used_seconds	int	Secondes utilisées depuis le dernier octroi mensuel
remaining_seconds	int	Secondes restantes
total_seconds	int	Secondes totales
usage_percent	int	Pourcentage d'utilisation (0-100)

PUT /api/user

Corps de la requête

Champ	Type	Requis	Description
name	string	No	Nom d'affichage (max 255)
email	string	Non	Nouvel e-mail (doit être unique)
avatar	file	No	Fichier image (max 5 Mo)

Réponse 200

{
    "id": 1,
    "name": "New Name",
    "email": "[email protected]",
    "avatar": "https://..."
}

Notifications

GET /api/notifications

Obtenir les 10 notifications les plus récentes.

Réponse

[
    {
        "id": "abc123",
        "title": "Task Completed",
        "message": "Meeting Recording has been transcribed.",
        "read_at": null,
        "created_at": "2026-03-02T10:45:00+08:00"
    }
]

POST /api/notifications/mark-all-as-read

Marquer toutes les notifications non lues comme lues.

Response 200

{
    "success": true
}

Paiement

GET /api/checkout/{plan}

Obtenir une URL de paiement Paddle pour un plan d'abonnement.

Paramètres de chemin

Paramètre	Description
plan	`test` / `month` / `year`

Réponse

Renvoie un objet d options de paiement Paddle. Renvoie 404 pour un plan invalide.

GET /api/health

Point de terminaison public de vérification de santé. Aucune authentification requise.

Réponse 200

{
    "status": "ok"
}

Lire les conditions · Lire la politique de confidentialité · Retour à l accueil