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.
Request Specify model (diffio-flash, diffio-pro, or any ID from GET /models) and optional label or sampling.
Path parameters Field Type Required Description # project_idstring Required: YesUnique identifier of the project.
Headers Field Type Required Description # Diffio-End-Userstring Required: 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-Keystring Required: 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 Field Type Required Description # modelstring Required: YesModel ID from GET /models, such as diffio-flash, diffio-pro, diffio-4.7-flash, or diffio-4.7-pro. # samplingobject Required: NoOptional advanced sampling overrides object. # labelstring Required: NoOptional caller-defined name for this generation (up to 120 characters), such as "Take 1".
Request
Python Node.js cURL JSON
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" ,
) import { DiffioClient } from "diffio"
const client = new DiffioClient ({
apiKey : process . env . DIFFIO_API_KEY ,
})
const generation =
await client . generations . create (
"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe" ,
{
model : "diffio-flash" ,
label : "Take 1" ,
},
{ idempotencyKey : "v2docs-g-mwe8tm1g" },
) curl -X POST "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/generations" \
-H "Authorization: Bearer $ DIFFIO_API_KEY" \
-H "Idempotency-Key: v2docs-g-mwe8tm1g" \
-H "Content-Type: application/json" \
-d '{
"model": "diffio-flash",
"label": "Take 1"
}' {
"model" : "diffio-flash" ,
"label" : "Take 1"
} 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 Field Type Present Description # idstring Always Unique generation identifier (UUID). # objectstring Always Resource type, always "generation".generation # statusstring Always Lifecycle state: queued, processing, complete, or failed.queuedprocessingcompletefailed # modelstring | null Always Hosted model that ran or is running (such as diffio-4.7-flash or diffio-4.7-pro), or null. # stagestring | null Always Current worker stage (pending, preparing, transcribing, queued, starting, downloading, decoding, restoring, finalizing, uploading, then complete or failed), or null. # stage_progressobject | null Always Live worker progress while status is processing, or null before a worker reports progress and after completion.Fields below ↓ # queueobject | null Always Worker queue snapshot while the generation waits to start, or null otherwise.Fields below ↓ # errorobject | null Always Failure details when status is failed (also includes boolean retryable and nullable explanation on the wire), or null otherwise. # error.code string Always Stable snake_case generation failure code (such as restoration_failed, no_speech_detected, transcription_failed, upload_missing, or generation_failed). # error.message string Always Human-readable message explaining why the generation failed.
stage_progress 6 fieldsoverall_percent stage_percent bytes_done bytes_total available_through_seconds duration_seconds Field Type Present Description # stage_progress. overall_percent number Sometimes Overall generation completion percentage from 0 to 100, present once reported. # stage_progress. stage_percent number Sometimes Completion percentage of the current stage from 0 to 100, present once reported. # stage_progress. bytes_done number Sometimes Bytes transferred so far in a downloading or uploading stage. # stage_progress. bytes_total number Sometimes Total bytes to transfer in the current downloading or uploading stage. # stage_progress. available_through_seconds number Sometimes Seconds of restored output already playable via hls_master while processing. # stage_progress. duration_seconds number Sometimes Recording length in seconds as reported by the worker.
queue 6 fieldsposition connected_workers idle_workers busy_workers wait_reason message Field Type Present Description # queue. position integer | null Always Number of queued jobs ahead of this generation, or null. # queue. connected_workers integer | null Always Total workers connected to the queue, or null. # queue. idle_workers integer | null Always Connected workers currently idle, or null. # queue. busy_workers integer | null Always Connected workers currently running jobs, or null. # queue. wait_reason string | null Always Why the job is waiting (all_busy, no_workers, or next_in_line), or null. # queue. message string Always Human-readable message explaining why the generation is waiting.
Response 201Created.
Key fields Full (27 lines)
{
"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_model402Payment 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_denied404Not found. No project with that project_id exists for this account and end user. project_not_found409Conflict: 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_failed401Unauthorized: 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). 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