Vue d'ensemble des interfaces de la bibliothèque de ressources

Les interfaces de la bibliothèque de ressources servent à créer des groupes de ressources, soumettre des images, interroger le statut des ressources, synchroniser les ressources et lancer une autorisation de portrait par scan de code QR. Toutes les interfaces utilisent la même clé API de plateforme, sans signature supplémentaire ni appel à d'autres services.

Les conventions communes (adresse de base, authentification, limitation de débit, idempotence) sont décrites dans Authentification et conventions de base.

Interfaces détaillées :

Liste des interfaces

Structure de réponse unifiée

Succès :

{ "code": 0, "data": {}, "msg": "OK" }

En cas d'échec, le code de statut HTTP est identique à code, et data vaut null :

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

Structure réelle de data

data est un objet et non un tableau ; les champs concrets dépendent de l'interface. Les collections des interfaces de liste sont placées sous une clé nommée :

{
  "code": 0,
  "data": {
    "groups": [
      { "id": "group-1789069780-5762d1", "name": "我的角色素材", "type": "virtual" }
    ],
    "page": 1,
    "page_size": 20,
    "total": 4
  },
  "msg": "OK"
}

Ne partez pas du principe que data est directement un tableau. La liste des groupes se trouve dans data.groups, la liste des ressources dans data.assets. Pour lire une collection, passez par la clé nommée, et utilisez data.total pour déterminer s'il existe une page suivante.

Attention : les ressources enregistrées automatiquement peuvent ne pas avoir d'id

Pour les groupes de ressources enregistrés automatiquement par la plateforme, id et platform_group_id peuvent être des chaînes vides :

{ "id": "", "platform_group_id": "", "name": "自动登记素材", "type": "virtual" }

N'utilisez pas id comme clé unique pour stocker ou fusionner les résultats de liste, sinon plusieurs entrées enregistrées automatiquement s'écraseront mutuellement. Il est recommandé d'utiliser plutôt la combinaison platform_group_id || id || name, ou d'ignorer directement les entrées inutilisables pour les appels d'interface ultérieurs. La seule exception est l'échec d'authentification : lorsque la clé API est absente, erronée ou expirée, l'interface renvoie HTTP 401, avec le corps de réponse {"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}.

Préparer les variables

export LOCOPAL_API_KEY="sk-你的APIKey"
export LOCOPAL_BASE_URL="https://locopalai.com"
export LOCOPAL_IMAGE_URL="https://你的对象存储域名/person.png"

Description de l'ID de ressource

Le data.asset_id renvoyé par l'interface (égal à data.asset.id) est l'ID unique de la ressource. L'ID de ressource affiché dans la liste « Gestion des ressources » de la console est la même valeur ; les deux emplacements sont interchangeables et aucune correspondance n'est nécessaire dans le programme.

Les ressources appartiennent au compte et non à une clé API particulière. Sous le même compte, changer de clé, recréer une clé ou changer de groupe d'appel permet de continuer à interroger et à utiliser les ressources d'origine ; les autres comptes ne peuvent ni les voir ni les référencer.

Modèles et bibliothèque de ressources

Les ressources sont portées par la bibliothèque de ressources unifiée de la plateforme : importées une seule fois, les modèles suivants utilisent tous directement la même ressource, sans qu'il soit nécessaire de préparer une copie distincte pour un modèle ni de soumettre à nouveau une validation.

Par conséquent :

• Une ressource n'est importée qu'une seule fois ; lors d'un changement de modèle, seul le champ model de la requête change, l'ID de ressource reste inchangé ;
• Il n'est pas nécessaire de créer un groupe distinct pour chaque modèle, ni de préciser « dans quelle bibliothèque de ressources placer la ressource » ;
• Les ressources de portrait sont portées par la bibliothèque de ressources prenant en charge l'autorisation de vivacité ; les modèles prenant en charge leur référencement sont doubao-seedance-2.0-D, doubao-seedance-2.0-D-fast, doubao-seedance-2.0-D-mini, doubao-seedance-2.5-D, seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5 ; soumettre une ressource de portrait à un autre modèle renvoie une erreur lisible ; ne la convertissez pas en URL d'image ordinaire pour contourner la limitation.

Une fois le statut de la ressource passé à Active, elle peut être utilisée dans n'importe quel modèle prenant en charge le référencement de ressources, sans attendre une nouvelle préparation côté modèle.

Les ressources existantes antérieures à cette évolution seront préparées une fois par la plateforme lors de leur première référence par un modèle ; une fois la préparation terminée, leur comportement est identique à celui des ressources référencées directement ; les ressources nouvellement importées n'ont plus besoin de cette étape.