Skip to content

For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/create-generation.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Create a generation

Starts a speech restoration run on a project's recording using the specified model. Accepted while the upload is still in progress: the generation waits in queued and starts automatically once the project is ready.

POST https://api.diffio.ai/v2/projects/{project_id}/generations

  • Key scope: generations:write
  • Auth header:Authorization: Bearer <apiKey>
  • Body: JSON
  1. POST/projectsid
  2. POST/projects/{project_id}/generationsid
  3. GET/projects/{project_id}/generations/{generation_id}status
  4. GET/projects/{project_id}/generations/{generation_id}/mediafiles
Replays and conflicts, case by case
  • First request201Created. new generation
  • Same Idempotency-Key, same body201Created. the same generation id
  • Same Idempotency-Key, other model, sampling or label409Conflict: see error.code for which one. idempotency_key_conflict

Request

Specify model (diffio-flash, diffio-pro, or any ID from GET /models) and optional label or sampling.

Path parameters

FieldTypeRequiredDescription
#project_idstringRequired: YesUnique identifier of the project.

Headers

FieldTypeRequiredDescription
#Diffio-End-UserstringRequired: NoOptional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account.
#Idempotency-KeystringRequired: NoOptional key (up to 255 characters) for safe retries. Repeating the same request returns the original generation; changing model, sampling, or label returns 409 (idempotency_key_conflict).

Body fields

FieldTypeRequiredDescription
#modelstringRequired: YesModel ID from GET /models, such as diffio-flash, diffio-pro, diffio-4.7-flash, or diffio-4.7-pro.
#samplingobjectRequired: NoOptional advanced sampling overrides object.
#labelstringRequired: NoOptional caller-defined name for this generation (up to 120 characters), such as "Take 1".

Request

import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

generation = client.generations.create(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    model="diffio-flash",
    label="Take 1",
    idempotency_key="v2docs-g-mwe8tm1g",
)

Billed calls are not offered here; send this one from your code.

Response

Returns the new generation (status: "queued" or "processing").

Success: 201Created.

Response fields

FieldTypePresentDescription
#idstringAlwaysUnique generation identifier (UUID).
#objectstringAlwaysResource type, always "generation".generation
#statusstringAlwaysLifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed
#modelstring | nullAlwaysHosted model that ran or is running (such as diffio-4.7-flash or diffio-4.7-pro), or null.
#stagestring | nullAlwaysCurrent worker stage (pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, then complete or failed), or null.
#stage_progressobject | nullAlwaysLive worker progress while status is processing, or null before a worker reports progress and after completion.Fields below
#queueobject | nullAlwaysWorker queue snapshot while the generation waits to start, or null otherwise.Fields below
#errorobject | nullAlwaysFailure details when status is failed (also includes boolean retryable and nullable explanation on the wire), or null otherwise.
#error.codestringAlwaysStable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed).
#error.messagestringAlwaysHuman-readable message explaining why the generation failed.
stage_progress 6 fields
FieldTypePresentDescription
#stage_progress.overall_percentnumberSometimesOverall generation completion percentage from 0 to 100, present once reported.
#stage_progress.stage_percentnumberSometimesCompletion percentage of the current stage from 0 to 100, present once reported.
#stage_progress.bytes_donenumberSometimesBytes transferred so far in a downloading or uploading stage.
#stage_progress.bytes_totalnumberSometimesTotal bytes to transfer in the current downloading or uploading stage.
#stage_progress.available_through_secondsnumberSometimesSeconds of restored output already playable via hls_master while processing.
#stage_progress.duration_secondsnumberSometimesRecording length in seconds as reported by the worker.
queue 6 fields
FieldTypePresentDescription
#queue.positioninteger | nullAlwaysNumber of queued jobs ahead of this generation, or null.
#queue.connected_workersinteger | nullAlwaysTotal workers connected to the queue, or null.
#queue.idle_workersinteger | nullAlwaysConnected workers currently idle, or null.
#queue.busy_workersinteger | nullAlwaysConnected workers currently running jobs, or null.
#queue.wait_reasonstring | nullAlwaysWhy the job is waiting (all_busy, no_workers, or next_in_line), or null.
#queue.messagestringAlwaysHuman-readable message explaining why the generation is waiting.
Other response fields34 fields
FieldTypePresentDescription
#project_idstringAlwaysIdentifier of the parent project.
#requested_modelstring | nullAlwaysModel name sent in the request (hosted model, tier alias, or retired model), or null.
#substitutedbooleanAlwaysTrue when requested_model was a retired model name and ran on the current hosted model of the same tier; false for hosted names and aliases.
#price_per_hour_usdnumber | nullAlwaysList price per hour in USD applied to this generation (for retired models, the lower of the requested and serving models' list prices), or null.
#warningsarrayAlwaysNon-fatal warnings recorded during processing (the generation still runs).Fields below
#labelstring | nullAlwaysCaller-supplied label (up to 120 characters), Transcript edit for an edit, or null when none was set.
#kindstringAlwaysGeneration kind: restore for a full recording restore, or edit for a transcript edit of a finished Pro generation.restoreedit
#source_generation_idstring | nullAlwaysFor kind: "edit", the Pro generation that was edited; null for restore.
Show all 17 fields (9 more)
FieldTypePresentDescription
#editobject | nullAlwaysTranscript edit details and progress when kind is edit, or null for restore.Fields below
#transcript_editablebooleanAlwaysTrue when this result's transcript can be edited via POST .../edits (a finished Pro result with stored edit latents).
#duration_secondsnumber | nullAlwaysDuration of the restored output in seconds once known, or null.
#quality_scorenumber | nullAlwaysEstimated speech quality score of the result from 1 to 5, or null.
#transcription_statusstring | nullAlwaysWord-timed transcript status: preparing, ready, or failed; null when no transcription is reported.preparingreadyfailed
#files_availablearrayAlwaysSorted names of artifacts currently available from GET .../media (such as audio, video, hls_master, transcript, stems_manifest).
#stems_statusstring | nullAlwaysSeparated speech and background track status: preparing, ready, or failed; null when none are reported.preparingreadyfailed
#created_atstring | nullAlwaysISO 8601 UTC timestamp when the generation was created, or null.
#updated_atstring | nullAlwaysISO 8601 UTC timestamp when the generation last changed, or null.
warnings[] 3 fields
FieldTypePresentDescription
#warnings[].codestringAlwaysWarning code; unsupported_language when the transcript contains words in languages the model cannot restore.unsupported_language
#warnings[].languagesarraySometimesISO 639-1 language codes of unsupported words, ordered by word count.
#warnings[].messagestringAlwaysHuman-readable warning message.
edit 14 fields
FieldTypePresentDescription
#edit.edit_countinteger | nullAlwaysNumber of edits (each run of changed, inserted, or removed words between kept words counts once), or null.
#edit.max_windowsinteger | nullAlwaysMaximum number of 30-second windows this edit could restore, or null.
#edit.windowsinteger | nullAlwaysActual number of windows restored (or being restored) by the worker, or null before starting.
#edit.windows_doneinteger | nullAlwaysNumber of restore windows completed so far, or null.
#edit.rangesarrayAlwaysTime ranges on the recording (in seconds) covered by the restored windows.
#edit.ranges[].startnumberSometimesWindow start time in seconds.
#edit.ranges[].endnumberSometimesWindow end time in seconds.
#edit.billable_secondsinteger | nullAlwaysSeconds billed once complete (30 per restored window, 0 when no window was restored), or null until complete.
#edit.cut_secondsnumber | nullAlwaysSeconds trimmed from the recording by tighten, or null.
#edit.request_idstring | nullAlwaysCaller-supplied request_id from the edit request, or null.
#edit.languagestring | nullAlwaysPrimary language code used for the edit, or null.
#edit.tightenobject | nullAlwaysSilence-shortening settings applied by the edit, or null when none were requested.
#edit.tighten.close_removed_gapsbooleanAlwaysWhether silence left by removed words was closed.
#edit.tighten.max_pause_secondsnumber | nullAlwaysMaximum pause duration in seconds after shortening, or null when pauses were left unchanged.

Response 201Created.

Response: key fields
{
  "id": "ce832a32-a1ce-516a-b8bd-75457bd8517f",
  "object": "generation",
  "status": "processing",
  "stage": "preparing",
  "stage_progress": null,
  "queue": null,
  "error": null,
  "model": "diffio-4.7-flash"
}

Return codes

  • 201Created.Generation created and queued for restoration.
  • 400Bad request.
    Malformed JSON, or 4 more causes
    • Malformed JSON
    • Missing model
    • Invalid label or sampling
    • Oversized header
    • Unrecognized model
    invalid_jsonmissing_fieldinvalid_fieldinvalid_headerunknown_model
  • 402Payment required: see error.code for the billing problem.The account cannot pay for this restore (checked at the 60-second minimum until the upload is probed); see the error codes below. insufficient_creditneeds_payment_methodpayment_failedusage_limit_reacheddetails
  • 403Forbidden: the key lacks permission.Key is inactive or lacks generations:write. permission_denied
  • 404Not found.No project with that project_id exists for this account and end user. project_not_found
  • 409Conflict: see error.code for which one.
    Reused Idempotency-Key with different body fields, or 3 more causes
    • Reused Idempotency-Key with different body fields
    • The project failed or was removed
    • The API key was revoked
    • During admission
    idempotency_key_conflictgeneration_unavailabledetails
  • 500Server error.Generation record was created without starting or billing; retry with the same Idempotency-Key. generation_start_failed
  • 401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint
    • 401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
    • 405Client error. HTTP method not supported on this path; check the Allow header (code method_not_allowed).

Error codes

5 codes
StatusCodeMeaningAlso returned
402Payment required: see error.code for the billing problem.insufficient_creditYour API credit is used up, or cannot cover this file.estimated_cost_cents remaining_credit_cents
402Payment required: see error.code for the billing problem.needs_payment_methodCard billing accounts: no payment method, and the credit is used up or cannot cover this file.estimated_cost_cents remaining_credit_cents (when the credit was read)
402Payment required: see error.code for the billing problem.payment_failedA payment for API usage failed, or the last invoice of ended card billing is unpaid.details omitted
402Payment required: see error.code for the billing problem.usage_limit_reachedUnbilled usage reached $100; it is being charged now.details omitted
409Conflict: see error.code for which one.idempotency_key_conflictIdempotency-Key was already used with different request fields.details omitted

Example error response

Error response
{
  "error": {
    "code": "insufficient_credit",
    "message": "This file needs about $1.25 of API credit and your balance is $0.40. Add credit in the developer dashboard to continue.",
    "request_id": "f064e4099097414da3fb5b37684ab1bb",
    "details": {
      "estimated_cost_cents": 125,
      "remaining_credit_cents": 40
    }
  }
}

Notes

  • Restores bill whole seconds rounded up with a 60-second minimum ($5/hour for diffio-4.7-flash, $10/hour for diffio-4.7-pro). Failed generations charge nothing.
  • Poll Get a generation (or use client.generations.wait(...) or generation.completed / generation.failed webhooks), then fetch URLs from Get a playback grant.
  • Only finished Pro generations (diffio-pro / diffio-4.7-pro) set transcript_editable: true for Edit a generation's transcript and Ask the edit assistant.

Report an issue with this page