---
title: "Depose une conversion"
method: POST
path: "/jobs"
tags: ["jobs"]
---

# Depose une conversion

`POST /jobs`

## Request

- Base URL: `https://jam-jam.org/api/v1`
- URL: `https://jam-jam.org/api/v1/jobs`
- Auth: one of:
  - HTTP bearer
  - none

Trois manieres de deposer une source, jamais melangees dans la meme
requete : un fichier (`multipart/form-data`, champ `file`), une URL
(`application/json`, `JobFromUrl`) ou du texte brut/ChordPro
(`application/json`, `JobFromText`). `output` est l'identifiant de
format cible tel que rendu par `GET /formats` (ex. `pdf-songbook`,
`midi`, `musicxml`). Le job est cree en file (`phase: queued`) : la
conversion elle-meme est asynchrone, suivre `Location` ou l'`id`
rendu. `Idempotency-Key` (en-tete) rend le rejeu sur d'authentiques
soucis reseau sans risque de double-conversion ni de double
decompte de quota (reponse `200` au lieu de `202`, meme `id`).

## Headers

- `Idempotency-Key` string
- `cf-turnstile-response` string
- `X-Jam-Anon` string
- `X-Jam-Anon-Token` string

## Request body

- union
  - JobFromUrl
    - `url` string, uri, required
    - `output` string, required
    - `inputFormat` string
    - `options` object: Pour output=backing-audio, voir BackingAudioOptions.
    - `deliver` 'download' | 'carnet'
  - JobFromText
    - `text` string, required
    - `output` string, required
    - `inputFormat` string
    - `options` object: Pour output=backing-audio, voir BackingAudioOptions.
    - `deliver` 'download' | 'carnet'

## Response `200`

Rejeu idempotent, job existant, aucune unite consommee

- Job
  - `id` string, required
  - `phase` 'queued' | 'running' | 'done' | 'failed' | 'cancelled', required
  - `percent` integer, required
  - `inputFormat` string, required
  - `outputFormat` string, required
  - `createdAt` string, date-time, required
  - `startedAt` string, date-time
  - `endedAt` string, date-time
  - `expiresAt` string, date-time, required
  - `queuePosition` integer
  - `etaS` integer
  - `steps` JobStep[], required
    - `id` string, required
    - `label` string, required: Cle i18n
    - `state` 'pending' | 'running' | 'done' | 'skipped' | 'failed', required
    - `startedAt` integer
    - `endedAt` integer
    - `percent` integer, required
  - `artifacts` JobArtifact[], required
    - `id` string, required
    - `kind` 'songbook' | 'file', required
    - `format` string, required
    - `mediaType` string, required
    - `bytes` integer, required
    - `sha256` string, required
    - `filename` string, required
  - `problem` Problem
    - `type` string, uri, required
    - `title` string, required
    - `status` integer, required
    - `code` 'bad-request' | 'unsupported-pair' | 'invalid-token' | 'account-required' | 'premium-required' | 'insufficient-scope' | 'not-visible' | 'payload-too-large' | 'unsupported-media-type' | 'unprocessable-entity' | 'conflict' | 'profile-required' | 'declaration-required' | 'sharing-suspended' | 'carnet-full' | 'source-too-long' | 'no-music' | 'corrupt-input' | 'site-walled' | 'url-not-allowed' | 'media-link-unsupported' | 'idempotency-conflict' | 'turnstile-required' | 'anon-quota-exhausted' | 'quota-exhausted' | 'read-quota-exceeded' | 'write-quota-exceeded' | 'stems-quota-exceeded' | 'stems-busy' | 'api-premium-required' | 'verification-required' | 'invalid-request' | 'invalid-idempotency-key' | 'unavailable' | 'upload-interrupted' | 'upload-failed' | 'too-large' | 'too-long' | 'invalid-audio' | 'model-unavailable' | 'in-progress' | 'storage-full' | 'storage-unavailable' | 'expired' | 'not-ready' | 'processing-failed' | 'invalid-result' | 'interrupted' | 'rate-limited' | 'queue-full' | 'client-quota' | 'busy' | 'job-pending' | 'job-expired' | 'job-failed' | 'not-found' | 'engine-unavailable' | 'internal', required
    - `detail` string
    - `instance` string
    - `retryAfter` integer
    - `quota` Usage
      - `ownerKind` 'anon' | 'user' | 'api', required
      - `unlimited` boolean, required
      - `conversion` QuotaBucket, required
        - `used` integer, required
        - `limit` integer, nullable, required
        - `window` 'rolling-24h' | 'iso-week' | 'calendar-month' | 'day-utc', required
        - `resetsAt` string, date-time, required
      - `carnet` QuotaBucket
        - `used` integer, required
        - `limit` integer, nullable, required
        - `window` 'rolling-24h' | 'iso-week' | 'calendar-month' | 'day-utc', required
        - `resetsAt` string, date-time, required
      - `read` QuotaBucket
        - `used` integer, required
        - `limit` integer, nullable, required
        - `window` 'rolling-24h' | 'iso-week' | 'calendar-month' | 'day-utc', required
        - `resetsAt` string, date-time, required
      - `write` QuotaBucket
        - `used` integer, required
        - `limit` integer, nullable, required
        - `window` 'rolling-24h' | 'iso-week' | 'calendar-month' | 'day-utc', required
        - `resetsAt` string, date-time, required
      - `stems` QuotaBucket
        - `used` integer, required
        - `limit` integer, nullable, required
        - `window` 'rolling-24h' | 'iso-week' | 'calendar-month' | 'day-utc', required
        - `resetsAt` string, date-time, required
      - `scopes` string[], required: Portees reellement exercables par l'identite appelante.
    - `updatedAt` string, date-time: Membre d'extension (RFC 9457 §3.2), present UNIQUEMENT sur `409 conflict` : la valeur SERVEUR courante de `updatedAt`. Relire l'objet n'est donc pas necessaire pour rejouer une ecriture avec `If-Match`.
  - `digest` string: Condensat canonique du songbook (parite)
  - `computedOffline` false, required
  - `links` object, required
    - `self` string
    - `events` string
    - `result` string
    - `songbook` string

## Other responses

- `202`: Job cree
- `400`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `401`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `403`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `413`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `415`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `422`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `429`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).
- `503`: Toute erreur de cette API, quel que soit le code HTTP, est un `application/problem+json` (RFC 9457) avec ce meme schema : `code` est la valeur stable a tester par un client (le `status` HTTP peut varier legerement selon le contexte, `code` non). `quota` est renseigne pour les erreurs liees au quota (`quota-exhausted`, `anon-quota-exhausted`, `client-quota`).

---

[API](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api.md) · [All operations](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api/llms.txt) · [OpenAPI document](https://skmtc.dev/jam-jam/apis/jam-jam-convert-api/revisions/64cd41a46e4e?raw)