L’API PicassoIA vous permet d’exécuter les modèles d’image et de vidéo de PicassoIA depuis votre propre code :

1. Vous créez une prédiction pour un modèle.
2. Vous interrogez la prédiction jusqu’à ce qu’elle soit terminée.
3. Vous lisez les URL de sortie.

• URL de base : https://api.picassoia.com/v1
• Format : requêtes et réponses en JSON, encodées en UTF-8.
• Prix : les prédictions effectuées via l’API sont actuellement gratuites. Elles ne consomment aucun crédit.
• Qui peut l’utiliser : les comptes disposant du forfait Infinite.

Sommaire

• Authentification
• Démarrage rapide
• Modèles
• Points de terminaison
• L’objet prédiction
• Interrogation périodique et ETA
• Annulation
• Erreurs
• Limites

Authentification

Chaque requête doit comporter une API key dans l’en-tête Authorization :

Authorization: Bearer pia_sk_…

• Créer une clé. Vous créez vos clés sur picassoia.com, dans la section API keys de votre compte.
  • La clé complète n’est affichée qu’une seule fois, au moment de sa création. Conservez-la en lieu sûr.
  • Un compte peut détenir 2 clés à la fois. Pour libérer une place, révoquez-en une.
• Révoquer une clé. Une clé révoquée cesse immédiatement de fonctionner.
• Gardez vos clés côté serveur. Toute personne qui détient une clé peut lancer des prédictions sur votre compte : n’en placez donc jamais dans une page web ni dans une application mobile. L’API n’envoie aucun en-tête CORS, si bien que les navigateurs ne peuvent pas l’appeler directement.
• Changement de forfait. Vos clés sont conservées si votre forfait change. Sans forfait Infinite, la création de prédictions renvoie 403 plan_required. Vous pouvez toujours consulter, lister et annuler vos prédictions.

Démarrage rapide

1. Créez une prédiction :

curl -s -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-image/predictions \
  -H "Authorization: Bearer $PICASSOIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "a lighthouse at sunset, oil painting", "aspect_ratio": "16:9"}}'

La réponse (201 Created) est une prédiction à l’état starting :

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "model": "picassoia/picassoia-image",
  "input": {
    "prompt": "a lighthouse at sunset, oil painting",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "output_format": "jpg",
    "output_quality": 80
  },
  "output": null,
  "error": null,
  "status": "starting",
  "created_at": "2026-10-01T09:30:00.000Z",
  "started_at": null,
  "completed_at": null,
  "metrics": { "predict_time": null },
  "urls": {
    "get": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
    "cancel": "https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60/cancel"
  },
  "eta": { "seconds": 12, "next_poll_in_seconds": 6 }
}

2. Interrogez-la (attendez eta.next_poll_in_seconds entre deux appels) jusqu’à ce que status vaille succeeded, failed ou canceled :

curl -s https://api.picassoia.com/v1/predictions/api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60 \
  -H "Authorization: Bearer $PICASSOIA_API_KEY"

3. Lisez la sortie :

{
  "id": "api_3f9c2b7e8d1a4c6f9e0b1a2c3d4e5f60",
  "status": "succeeded",
  "output": ["https://…/lighthouse.jpg"],
  "metrics": { "predict_time": 6.4 },
  "eta": null
}

(Les autres champs sont omis ici.)

Node.js (fetch)

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_API_KEY}`,
  'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))

async function run(model, input) {
  const created = await fetch(`${API}/models/${model}/predictions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ input }),
  })
  let prediction = await created.json()
  if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)

  while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
    await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
    prediction = await (await fetch(prediction.urls.get, { headers })).json()
  }
  if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
  return prediction.output
}

const video = await run('picassoia/seedance-2.5-lite', {
  prompt: 'a paper boat sailing down a rainy street',
  duration: 5,
})
console.log(video) // "https://…/video.mp4"

Python (requests)

import os, time, requests

API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_API_KEY']}"}

def run(model, input):
    response = requests.post(f"{API}/models/{model}/predictions", json={"input": input}, headers=HEADERS)
    prediction = response.json()
    if not response.ok:
        raise RuntimeError(f"{prediction['code']}: {prediction['detail']}")
    while prediction["status"] not in ("succeeded", "failed", "canceled"):
        time.sleep((prediction.get("eta") or {}).get("next_poll_in_seconds", 2))
        prediction = requests.get(prediction["urls"]["get"], headers=HEADERS).json()
    if prediction["status"] != "succeeded":
        raise RuntimeError(prediction["error"] or prediction["status"])
    return prediction["output"]

images = run("picassoia/picassoia-image-editor-pro", {
    "prompt": "put the cat from image 1 on the sofa from image 2",
    "images": ["https://example.com/cat.png", "https://example.com/sofa.jpg"],
})
print(images)  # ["https://…/result.webp"]

Modèles

Le schéma exact de chaque modèle est également disponible au format JSON Schema : GET /v1/models/{owner}/{name} renvoie input_schema (avec chaque champ, ses limites et ses valeurs par défaut) et output_schema.

Images en entrée. Les champs d’image acceptent deux types de valeur :

• une URL https accessible publiquement ;
• une URL de données : data:image/png;base64,…, ou encore image/jpeg ou image/webp, jusqu’à 5 Mo chacune.

Les images doivent être au format PNG, JPEG ou WebP. PicassoIA conserve sa propre copie de chacune d’elles : dans la prédiction, input affiche donc l’URL de cette copie. Utilisez des URL pour tout fichier de plus de quelques centaines de Ko : le corps de la requête est limité à 10 Mo au total.

Les champs inconnus sont refusés, afin qu’une faute de frappe n’entraîne pas silencieusement l’utilisation d’une valeur par défaut. La réponse est 422 invalid_input.

picassoia/picassoia-image

Sortie : une liste de 1 ou 2 URL d’images.

picassoia/picassoia-image-editor-pro

Sortie : une liste de 1 ou 2 URL d’images.

picassoia/picassoia-video

Sortie : une URL MP4 (une chaîne).

picassoia/seedance-2.5-lite

Sortie : une URL MP4 (une chaîne).

Points de terminaison

Modèle

{
  "id": "picassoia/seedance-2.5-lite",
  "owner": "picassoia",
  "name": "seedance-2.5-lite",
  "title": "Seedance 2.5 Lite",
  "description": "Text or image to video with synchronized audio: …",
  "input_schema": { "type": "object", "properties": { "…": {} }, "required": ["prompt"], "additionalProperties": false },
  "output_schema": { "type": "string", "format": "uri" }
}

Créer une prédiction

POST /v1/models/{owner}/{name}/predictions avec le corps { "input": { … } }.

• L’API répond dès que le modèle a accepté la tâche, généralement en quelques secondes, avec la prédiction à l’état starting. Elle n’attend jamais le résultat.
• Si la prédiction échoue immédiatement, la réponse reste 201, avec la prédiction à l’état failed et son error. C’est le cas, par exemple, lorsque l’entrée est refusée par le filtre de sécurité.
• Si aucune prédiction n’a été créée, la réponse est une erreur : entrée non valide, forfait, trop de prédictions en cours, service indisponible.

Lister les prédictions

GET /v1/predictions renvoie vos prédictions effectuées via l’API, 50 par page, de la plus récente à la plus ancienne, toutes clés confondues.

• next est l’URL de la page suivante (…/v1/predictions?cursor=…), ou null sur la dernière page.
• previous vaut toujours null.
• Les prédictions que vous avez supprimées sur picassoia.com sont exclues.

Une prédiction est accessible avec n’importe laquelle de vos clés, et n’est jamais visible par quelqu’un d’autre.

L’objet prédiction

États.

La distinction entre starting et processing est une estimation, établie à partir de la position dans la file au moment de la création. Une nouvelle prédiction est toujours à l’état starting. Les trois derniers états sont définitifs : une prédiction qui a atteint l’un d’eux ne change plus jamais.

Erreurs d’une prédiction échouée. Le champ error d’une prédiction échouée contient l’un des messages suivants :

• L’entrée ou la sortie a été refusée par le filtre de sécurité. Le message se termine par (SAFETY_CHECKER_PICASSO_FILTER_S4).
• The prediction failed. You can try again.
• The prediction timed out. You can try again. La prédiction ne s’est pas terminée dans un délai de 3 heures.

Sorties. Les URL de sortie sont hébergées par PicassoIA. Téléchargez les fichiers que vous souhaitez conserver.

Interrogation périodique et ETA

eta.next_poll_in_seconds vous indique quand la prochaine interrogation sera utile :

1. À la moitié du temps estimé.
2. Lorsque le temps estimé est atteint.
3. Puis toutes les 2 secondes.

Exemple avec une estimation de 10 s : interrogez au bout de 5 s, puis de 10 s, puis toutes les 2 s. Interroger plus souvent ne vous donnera pas le résultat plus tôt.

Annulation

POST /v1/predictions/{id}/cancel :

Une prédiction annulée libère immédiatement sa place parmi vos 5 prédictions en cours.

Erreurs

Les erreurs sont renvoyées sous forme de « problem details » JSON, avec en plus un code stable destiné aux programmes :

{
  "title": "Too many predictions in progress",
  "detail": "This account can have up to 5 predictions queued or running at once, shared by its API keys and MCP connections, and 5 are. Wait for one to finish and try again.",
  "status": 429,
  "code": "concurrency_limit",
  "retry_after": 10,
  "limit": 5,
  "running": 5
}

invalid_fields. Une réponse 422 liste chaque champ en cause :

{
  "title": "Input validation failed",
  "status": 422,
  "code": "invalid_input",
  "detail": "input.duration: At 720p the longest clip is 10 seconds.",
  "invalid_fields": [
    { "type": "invalid_value", "field": "input.duration", "description": "At 720p the longest clip is 10 seconds." }
  ]
}

Limites