> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Voice from Description Task Status

> Monitor the progress of your AI-generated voice creation through real-time status updates.

Track every stage of your voice generation process with millisecond precision. This endpoint provides real-time visibility into voice synthesis tasks, enabling seamless integration with time-sensitive applications like live narration systems and interactive voice interfaces.

<Card icon="lightbulb" cta="Go to Create Voice from Description Endpoint" href="create-text-to-voice">
  This endpoint works in conjunction with the main `/text-to-voice` endpoint, which initiates the voice generation process and provides the essential `task_id` for status monitoring.
</Card>

## Monitoring Your Voice Generation

Implement intelligent status tracking with this Python example:

```python [expandable] theme={null}
def monitor_voice_creation(task_id, poll_interval=5):
    """
    Advanced status tracking with automatic recovery suggestions
    """
    status_guidance = {
        "SUCCESS": {"icon": "✅", "action": "download_voice"},
        "PENDING": {"icon": "⏳", "action": "wait"},
        "TIMEOUT": {"icon": "⏰", "action": "retry_or_contact"},
        "ERROR": {"icon": "❌", "action": "review_inputs"},
        "PAYMENT_REQUIRED": {"icon": "💳", "action": "add_credits"}
    }

    while True:
        response = requests.get(f"/text-to-voice/{task_id}", headers=headers)
        status_data = response.json()
        current_status = status_data.get('status')

        # Get status metadata
        guidance = status_guidance.get(current_status, {})
        print(f"{guidance.get('icon', 'ℹ️')} Status: {current_status}")

        # Handle terminal states
        if current_status in ["SUCCESS", "TIMEOUT", "ERROR", "PAYMENT_REQUIRED"]:
            print(f"Error details: {status_data.get('message', 'Contact support')}")
            print(f"Recommended action: {guidance.get('action', 'contact_support')}")
            if current_status == "SUCCESS":
                print(f"\n🎉 Voice generation completed!")
                print(f"Production ID: {status_data.get('run_id')}")
            return status_data

        time.sleep(poll_interval)
```

This polling mechanism gives you flexibility to build applications that can provide real-time feedback to users about their voice from description creations. You can adjust the polling interval based on your specific needs, checking more frequently for time-sensitive applications or less frequently for background tasks.

## Next Steps

Once your task shows a status of `SUCCESS`, you’ll receive a `run_id` in the response. This `run_id` is your key to accessing the generated sample audio files for the voices. Take this identifier and use it with the [`/text-to-voice-result/{run_id}`](get-text-to-vocie-run-result) endpoint to download your the sample voices, select the one that matches your desired characteristics and put it to work in your application.


## OpenAPI

````yaml get /text-to-voice/{task_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /text-to-voice/{task_id}:
    get:
      tags:
        - Apis
        - Text-to-Voice
      summary: Get Text-to-Voice Task Status
      description: Get the status of a text-to-voice task by its ID.
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/TaskIDParam'
            description: >-
              A unique identifier for the task. This is used to query the status
              of the text to voice task that is running. It is returned when a
              create request is made for text to voice.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrchestratorPipelineResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    TaskIDParam:
      type: string
      title: Task ID
      description: >-
        This parameter represents a unique identifier for a task. It is used in
        various API endpoints to query the status or result of a specific task.
        The `task_id` is typically returned when a task is created.
    OrchestratorPipelineResult:
      properties:
        status:
          $ref: '#/components/schemas/TaskStatus'
        run_id:
          type:
            - integer
            - 'null'
          title: Run ID
      type: object
      title: OrchestratorPipelineResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TaskStatus:
      type: string
      enum:
        - SUCCESS
        - PENDING
        - TIMEOUT
        - ERROR
        - PAYMENT_REQUIRED
      title: TaskStatus
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The `x-api-key` is a custom header required for authenticating requests
        to our API. Include this header in your request with the appropriate API
        key value to securely access our endpoints. You can find your API key(s)
        in the 'API' section of our studio website.

````