Référence de l’API d’entraînement

Les commandes et le code restent en anglais dans toutes les langues. Remplacez les espaces réservés en majuscules par les valeurs de votre compte et de votre tâche payante ; ne collez pas de vraies clés dans des carnets ou des journaux partagés.

Cycle de vie des ressources API

Un devis, une tâche payante et une session d’entraînement sont des ressources distinctes.

Devis Valider la configuration et le prix actuel
Tâche Créer et régler le paiement approuvé
Session Choisir l’environnement d’exécution et la référence incluse
Préparation Produire des manifestes de données vérifiés
Rapport Consigner l’entraînement réel et les métadonnées de l’artefact

Authentification et règles des requêtes

Utilisez HTTPS avec Authorization: Bearer et une clé API de compte dotée de la portée ai:training. Envoyez Accept: application/json ; ajoutez Content-Type: application/json pour les corps JSON. Toutes les ressources appartiennent à un compte. Le groupe de routes est limité à 30 requêtes par minute, avec des contrôles supplémentaires lorsqu’ils sont configurés. Les ID des exemples sont des espaces réservés et non des ressources partagées.

Les ID de devis, UUID de tâche, ID de session, ID de modèle et ID d’artefact sont des identifiants différents.
Après une interruption réseau, lisez l’état actuel avant de répéter une écriture.
N’utilisez pas le texte des pages publiques ni les paramètres d’URL de tarification dans les requêtes API.

export TRAINING_API='https://fusionpointai.com/api/v1/training'
# Set the key securely as shown in Quickstart.
export JOB_UUID='REPLACE_WITH_YOUR_JOB_UUID'
export SESSION_ID='REPLACE_WITH_YOUR_SESSION_ID'
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'

Requêtes, réponses et états

Créez un devis à partir d’une configuration admissible, puis la tâche correspondante et terminez le paiement approuvé avant d’ouvrir une session. Les endpoints de projet autorisent l’accès payant existant au modèle de référence et permettent de demander un programme ou des leçons, sans créer de facture ni modifier les prix. Les réponses de session incluent la configuration, la référence choisie, les manifestes de données, l’étape signalée et le rapport. Préparation et rapports sont des requêtes distinctes ; les états de tâche et de session le sont aussi.

L’autorisation de projet nécessite provider et reference_model_id ; les requêtes au modèle de référence nécessitent aussi action et objective.
Les exemples du modèle de référence se limitent au matériel d’entraînement approuvé ; les lignes de validation et de test final restent locales.
Les rapports de fin décrivent un véritable artefact local ; vérifiez ses données d’intégrité et d’évaluation.

POST /api/v1/training/quotes
reference_model_id     required eligible integer model ID
training_plan_id       required public provider-plan integer ID
mode                   automatic | advanced
objective              required string, 10..4000 characters
language               required string, at most 120 characters
performance_criteria   required string, 10..2000 characters
student_release_slug   optional eligible slug, at most 190 characters
method                 optional eligible method, at most 80 characters
dataset_megabytes      optional integer, 1..1000000
gpu_count              optional integer, 1..128
delivery               optional: artifact | hosted
execution_target       optional: fusionpointai_hosting | customer_datacenter | colab

Availability and approved plan policies can impose narrower constraints.
Do not submit price, fixed_total, currency, price_version_id or model_training.

{
  "reference_model_id": 123,
  "training_plan_id": "<INTEGER_FROM_YOUR_PROVIDER_PLAN>",
  "mode": "advanced",
  "objective": "Train a German support-message classifier.",
  "language": "German",
  "performance_criteria": "Evaluate per-class precision and recall on held-out data.",
  "student_release_slug": "<ELIGIBLE_STUDENT_RELEASE_SLUG>",
  "method": "LoRA",
  "dataset_megabytes": 8,
  "gpu_count": 1,
  "delivery": "artifact"
}

# Save the body as quote.json; replace ID placeholders with integers.
# Automatic mode omits student_release_slug and method.
curl --fail-with-body --silent --show-error "$TRAINING_API/quotes" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @quote.json
# Save {"quote":"YOUR_QUOTE_UUID"} as job.json.
# Creates a native job/invoice; this is not payment confirmation.
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @job.json
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs/$JOB_UUID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'

POST /api/v1/training/quotes: 201
{quote: UUID, currency: ISO_CODE, fixed_total: DECIMAL_STRING, expires_at: ISO_8601}

POST /api/v1/training/jobs: {"quote":"OWNED_QUOTE_UUID"}
201 for a newly created job; 200 when an accepted quote reuses its job.
Job fields:
id                job UUID
status            native job state, such as awaiting_payment
progress_percent  recorded progress, not an independent quality score
invoice_id        owned native invoice ID or null
created_at        ISO 8601 timestamp
completed_at      ISO 8601 timestamp or null
training_session  null or {id, status, step, delivery, verification}

GET /api/v1/training/jobs:
{data: JOB_ARRAY, current_page: INTEGER, last_page: INTEGER, per_page: 50, total: INTEGER}

This is a response-shape reference, not a fabricated live response.

# Save as session.json, using your paid job UUID and optional reference ID:
# {"job":"YOUR_PAID_JOB_UUID","runtime":"customer_datacenter","reference_model_id":123}
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @session.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'
# One preparation batch; inspect progress before another request.
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/prepare" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'

Session response fields (shape reference, not a fabricated live result):
id                  session UUID
job                 owned job UUID
status              preparing | ready | running | evaluating | completed | failed | cancelled
configuration       approved method, student_checkpoint, sdk_training and selected reference
reference_model_id  selected integer reference ID
expires_at          ISO 8601 access expiry
step                last reported integer step
datasets[]          {split, rows, bytes, sha256}
report              current report object; event metrics live under report.last_event.metrics
delivery            runtime_local
verification        runtime_reported

curl --fail-with-body --silent --show-error \
  "$TRAINING_API/sessions/$SESSION_ID/datasets/train" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/x-ndjson' --output train.jsonl
# Use /datasets/validation for the other supported split.
sha256sum train.jsonl
# Compare bytes, rows and SHA-256 with the session manifest.
# For published server-side artifacts only, not the local SDK ZIP:
# GET /api/v1/training/jobs/{job}/artifacts/{file}

POST /api/v1/training/sessions/{session}/events
Content-Type: application/json

state         required: running | evaluating | failed
step          required integer: 0..2000
total_steps   required integer: 1..2000
metrics       optional; only loss and eval_loss, each 0..1000000
error_code    optional: training_failed | evaluation_failed | runtime_unavailable |
              dataset_invalid | report_failed

Send actual trainer observations, never sample or invented metrics.

# Build the body from a REAL SDK report; requires jq.
jq '{artifact_name:"model-package.zip",report:.completion_report}' \
  customer-model-run-001/training-report.json > completion.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/complete" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @completion.json
# Cancel eligible service state, not the operating-system process:
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/cancel" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'

curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/authorize' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123}'
# The response identifies the owned paid job/grant and access expiry.

curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/teacher' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123,"action":"lessons","objective":"Classify support messages into agreed categories.","topic":"ambiguous_requests","count":2,"approved_examples":["A reviewed support training example."]}'
# Send only explicitly approved training examples. Never send held-out rows.
# Curriculum action returns topics; lessons action returns text/topic examples.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
print("Session:", session["id"])
print("Status:", session["status"])
print("Last reported step:", session["step"])
# Inspection is read-only; status and step are server-reported state.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
for manifest in session["datasets"]:
    print(
        manifest["split"],
        "rows:", manifest["rows"],
        "bytes:", manifest["bytes"],
        "sha256:", manifest["sha256"],
    )
# These are server-provided manifest values, not a local integrity pass.

import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
server_report = session.get("report")
runtime_report = server_report.get("runtime") if isinstance(server_report, dict) else None
if (
    session.get("status") == "completed"
    and isinstance(runtime_report, dict)
    and runtime_report.get("artifact_sha256") == os.environ["LOCAL_ARTIFACT_SHA256"]
    and server_report.get("delivery") == "runtime_local"
    and server_report.get("verification") == "runtime_reported"
):
    print("Server report matches the local artifact digest.")
else:
    print("Completion is not confirmed for this local artifact.")
# Reconcile by reading state; do not repeat training or invent a result.

Erreurs et intégration fiable

Appuyez-vous sur le statut HTTP et les détails de validation renvoyés au lieu de supposer que chaque erreur est temporaire. Attendez-vous à 401 pour les requêtes non authentifiées, 403 pour un accès refusé, 404 pour une ressource absente ou appartenant à un autre compte, 409 pour un état incompatible, 422 pour une entrée invalide et 429 en cas de limitation du débit. Les défaillances du fournisseur ou de l’environnement d’exécution peuvent renvoyer d’autres erreurs. Le SDK expose APIError sans renvoyer la sortie brute d’un service amont susceptible de contenir des secrets.

Les événements autorisent running, evaluating ou failed ; les clés de métriques sont loss et eval_loss.
step et total_steps sont limités à 2000 ; total_steps doit être positif.
Le corps de complete doit contenir artifact_name et chacun des champs de rapport présentés dans l’exemple.

401  Authentication missing or invalid
403  Account/key scope or access denied
404  Resource missing, non-owned or intentionally hidden
409  Invalid session transition, runtime, paid-access or model configuration
410  Writable session expired
422  Invalid request fields or completion criteria not met
429  Request rate limited
502  Upstream reference data malformed or preparation failed

Do not retry a write blindly. Read session state and inspect the response.
Keep error_code distinct from the HTTP status. Never log authorization.

POST /api/v1/training/sessions/{session}/complete
artifact_name                 safe filename ending in .zip, max 160 characters
report.training_steps         integer 1..2000
report.weights_before_sha256  lowercase SHA-256 of actual pre-training weights
report.weights_after_sha256   lowercase SHA-256 of actual changed weights
report.artifact_sha256        lowercase SHA-256 of the real local ZIP
report.artifact_bytes         integer 1..107374182400
report.eval_loss_before       finite number >0 and <=1000000
report.eval_loss_after        finite number >=0 and <=1000000
report.base_repository        pinned student repository, max 255 characters
report.base_revision          lowercase immutable 40-character revision
report.method                 SFT | LoRA | QLoRA

Values must match the approved session and actual local training.
Additional report keys are rejected. This body does not upload the ZIP.

import os
from fusionpointai_training import TrainingClient
from fusionpointai_training.errors import APIError

client = TrainingClient(
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
    timeout=30.0,
    max_get_retries=2,
)
try:
    session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
except APIError:
    # GET retries are bounded. Do not blindly retry a write after an error.
    print("Session inspection failed; check access and current server state.")
else:
    print("Status:", session["status"])
# Never print the API key, authorization headers, or response secrets.