Referencia de la API de entrenamiento

Los comandos y el código se mantienen en inglés en todos los idiomas. Sustituye los marcadores en mayúsculas por valores de tu cuenta y de tu tarea de pago; no pegues claves reales en cuadernos ni registros compartidos.

Ciclo de vida de los recursos de la API

Una cotización, una tarea de pago y una sesión de entrenamiento son recursos distintos.

Cotización Validar configuración y precio actual
Tarea Crear y completar el pago aprobado
Sesión Seleccionar el entorno de ejecución y la referencia incluida
Preparación Generar manifiestos de datos verificados
Informe Registrar el entrenamiento real y los metadatos del artefacto

Autenticación y reglas de las solicitudes

Usa HTTPS con Authorization: Bearer y una clave API de cuenta que tenga el ámbito ai:training. Envía Accept: application/json; añade Content-Type: application/json a los cuerpos JSON. Todos los recursos pertenecen a una cuenta. El grupo de rutas tiene un límite de 30 solicitudes por minuto, con controles adicionales cuando estén configurados. Los ID de los ejemplos son marcadores, no recursos compartidos.

Los ID de cotización, UUID de tarea, ID de sesión, ID de modelo e ID de artefacto son identificadores distintos.
Tras una interrupción de red, consulta el estado actual antes de repetir una escritura.
No uses el texto de páginas públicas ni parámetros de consulta de precios en las solicitudes 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'

Solicitudes, respuestas y estados

Crea una cotización con una configuración apta, crea la tarea a partir de ella y completa el flujo de pago aprobado antes de abrir una sesión. Los endpoints de proyecto autorizan el acceso de pago existente al modelo de referencia y permiten solicitar un currículo o lecciones sin generar facturas ni cambiar precios. Las respuestas de sesión incluyen la configuración, la referencia seleccionada, los manifiestos de datos, el paso informado y el informe. La preparación y los informes son solicitudes distintas; los estados de tarea y sesión también.

La autorización del proyecto requiere provider y reference_model_id; las solicitudes al modelo de referencia también requieren action y objective.
Los ejemplos del modelo de referencia se limitan al material de entrenamiento aprobado; las filas de validación y prueba final permanecen locales.
Los informes de finalización describen un artefacto local real e incluyen datos de integridad y evaluación que deben comprobarse.

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.

Errores e integración segura

Usa el estado HTTP y los detalles de validación devueltos, en vez de suponer que todos los errores son transitorios. Espera 401 para solicitudes no autenticadas, 403 para acceso denegado, 404 para recursos inexistentes o que no pertenecen a la cuenta, 409 para estados incompatibles, 422 para entradas no válidas y 429 para limitación de solicitudes. Los fallos del proveedor o del entorno de ejecución pueden devolver otros errores. El SDK expone APIError sin devolver la salida sin procesar del proveedor que podría contener secretos.

Los eventos admiten running, evaluating o failed; las claves de métricas son loss y eval_loss.
step y total_steps están limitados a 2000; total_steps debe ser positivo.
El cuerpo de complete requiere artifact_name y todos los campos del informe que aparecen en el ejemplo.

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.