Ressources

Après leur soumission, les ressources sont traitées de manière asynchrone par la plateforme ; ce n'est qu'après le passage du statut de Processing à Active qu'elles peuvent être utilisées pour les tâches vidéo.

Soumettre une ressource image

Méthode d'authentification

Authorization: Bearer <API_KEY>.

Corps de la requête · application/json

Seul l'un des champs image_url et data_url peut être soumis. image_url peut aussi être data:image/...;base64,..., que la plateforme traitera comme une image intégrée. Lors de l'utilisation d'une URL distante, l'adresse doit être une adresse http(s):// téléchargeable publiquement par la plateforme (http et https sont pris en charge), sans dépendre de cookies, de Referer, d'une page de connexion ni d'une session de navigateur, et doit rester valide pendant le traitement par la plateforme.

Une image_url distante passe d'abord par le cache de relais rapide de la plateforme, puis est mise en miroir par la bibliothèque de ressources ; une image ordinaire peut généralement être traitée en quelques secondes. La plateforme prend également en charge les images intégrées : vous pouvez écrire la valeur de image_url sous la forme data:image/...;base64,..., ou utiliser le champ distinct data_url. Pour une image déjà présente localement sur le client, la soumission intégrée permet d'économiser un téléchargement externe supplémentaire.

data_url envoie l'image entière en base64 (environ 1,33 fois le volume de l'image d'origine) ; ne l'utilisez que lorsque l'image ne peut vraiment pas disposer d'une adresse publique : par exemple, une image derrière une adresse nécessitant une connexion, sur un réseau interne, ou uniquement disponible en fichier local. Avec data_url, la durée d'import dépend de la taille de l'image et de la bande passante de l'appelant ; la plateforme écrit l'image dans un relais temporaire à court terme, et non dans le stockage permanent de ressources de la plateforme. Une fois la mise en miroir par la bibliothèque de ressources terminée et le statut passé à Active, l'aperçu utilise en priorité le preview_url renvoyé par la bibliothèque de ressources ; le fichier temporaire est nettoyé automatiquement par le service de relais.

Les ressources image ne peuvent être soumises qu'à un groupe virtual ; les ressources d'un groupe real sont produites par le processus d'autorisation de portrait par scan de code QR.

request_id peut également être soumis via l'en-tête Idempotency-Key. Lorsque le même compte soumet à nouveau avec le même request_id, la plateforme renvoie la même ressource créée avec succès la première fois et ne recrée pas de ressource en amont. Si request_id n'est pas soumis, la plateforme génère automatiquement une valeur stable à partir du compte, du groupe, du titre et de la charge utile de l'image d'origine ; une nouvelle tentative avec la même image et le même titre peut également être réutilisée en toute sécurité.

Exemple de requête

curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/assets" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "$LOCOPAL_IMAGE_URL",
  "tags": ["人物", "正面"]
}
JSON

Pour une image locale, soumettez plutôt data_url :

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "file_name": "person.png",
  "data_url": "data:image/png;base64,iVBORw0KGgo..."
}

Si le client souhaite continuer à utiliser le champ image_url, il peut également soumettre directement une image intégrée :

{
  "group_id": "group-1789069780-5762d1",
  "request_id": "brand-character-front-001",
  "title": "角色正面定妆图",
  "image_url": "data:image/png;base64,iVBORw0KGgo..."
}

Paramètres de réponse

Corps de la réponse

{
  "code": 0,
  "data": {
    "asset_id": "asset-20260911035115-etexu",
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Processing",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069876
    }
  },
  "msg": "图片素材已提交"
}

Une soumission réussie signifie seulement que la ressource a été acceptée ; vous devez encore interroger son statut avant de soumettre une tâche vidéo.

Réponses d'erreur

Interroger une ressource unique

Méthode d'authentification

Authorization: Bearer <API_KEY>.

Paramètres de la requête · path

Exemple de requête

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets/asset-20260911035115-etexu" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Paramètres de réponse

Valeurs de data.asset.status et traitement correspondant :

Corps de la réponse

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "platform_asset_id": "asset-20260911035115-etexu",
      "kind": "image",
      "title": "角色正面定妆图",
      "group_id": "group-1789069780-5762d1",
      "status": "Active",
      "error_message": null,
      "note": null,
      "tags": [],
      "mime_type": null,
      "bytes": null,
      "created_at": 1789069876,
      "updated_at": 1789069877
    }
  },
  "msg": "OK"
}

Un échec de validation renvoie également HTTP 200, la cause de l'échec se trouvant dans error_message :

{
  "code": 0,
  "data": {
    "asset": {
      "id": "asset-20260911035115-etexu",
      "status": "Failed",
      "error_message": "素材处理失败"
    }
  },
  "msg": "OK"
}

Réponses d'erreur

Interroger la liste des ressources

Méthode d'authentification

Authorization: Bearer <API_KEY>.

Paramètres de la requête · query

Exemple de requête

curl "$LOCOPAL_BASE_URL/api/v1/materials/assets?page=1&page_size=20&group_id=group-1789069780-5762d1" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY"

Paramètres de réponse

Corps de la réponse

{
  "code": 0,
  "data": {
    "assets": [
      {
        "id": "asset-20260911035115-etexu",
        "platform_asset_id": "asset-20260911035115-etexu",
        "kind": "image",
        "title": "角色正面定妆图",
        "group_id": "group-1789069780-5762d1",
        "status": "Active",
        "error_message": null,
        "note": null,
        "tags": [],
        "mime_type": null,
        "bytes": null,
        "created_at": 1789069876,
        "updated_at": 1789069877
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  },
  "msg": "OK"
}

Réponses d'erreur