Live Ingest & Forwarding

When your source video cannot be “pushed” directly to our network, the Live Ingest & Forwarding feature allows you to ingest it from any external source and redistribute it to one or more destinations. Functioning as a powerful stream relay, it provides an API-driven solution for workflows where direct publishing isn’t possible.

The process consists of two main actions:

• Ingest (Pull): Our service actively ingests a live video feed by “pulling” from a source URL you provide.
• Forward (Push): The ingested stream is then re-pushed to one or more RTMP destination URLs you define, enabling content syndication to other platforms or CDNs.

Authentication

All API requests must be authenticated using three query parameters appended to the endpoint URL: n, r, and k.

• n: Your CDNetworks platform account name.
• r: A unique random string (max 32 characters). A Unix timestamp is a good choice.
• k: A 32-character MD5 signature.

MD5 Signature Calculation

The signature k is calculated as md5(r + key), where key is your secret API key.

1. Get Your Secret Key: Contact CDNetworks customer service to obtain your secret key.
2. Generate a Random String: Create a unique string for r. Example: r = 1409284800.
3. Concatenate: Append your secret key to the random string.
   • If key = 012f37a3f2952, the combined string is 1409284800012f37a3f2952.
4. Calculate MD5 Hash: Compute the MD5 hash of the combined string to get k.
   • k = md5("1409284800012f37a3f2952") which results in b9fed80be752551834eec3e52fa94115.

Task Management

This feature can be controlled in two ways:

• Real-time Tasks: Start and stop the relay immediately for an active live stream.
• Scheduled Tasks: Pre-configure tasks with specific start and end times for streams that are not yet live.

The following endpoint is used to create, stop, update, and resume forwarding tasks.

• HTTP Method: POST
• Endpoint: http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action
• Headers: Content-Type: application/json

Example Request URL:

http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action?n=your_account&r=1409284800&k=b9fed80be752551834eec3e52fa94115

Example Request Body (cmd=1, Create Task):

{
    "transcallbackurl": "http://example.com/api/callback",
    "cmd": "1",
    "type": "live",
    "list": [
        {
            "id": "task_unique_id_001",
            "src": [
                {
                    "url": "http://source.example.com/live/stream1.flv",
                    "wmImage": "http://source.example.com/assets/logo.jpg",
                    "wmGravity": "TOP_LEFT"
                },
                {
                    "url": "http://backup.example.com/live/stream1.flv"
                }
            ],
            "forward": [
                {
                    "url": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)"
                },
                {
                    "url": "rtmp://[dest2.example.com/live/output](https://dest2.example.com/live/output)"
                }
            ],
            "start": "1495177025000",
            "end": "1495184225000",
            "fops": {
                "bps": "1200000",
                "res": "1280x720",
                "fps": "25",
                "vcodec": "libx264",
                "forced_gopInterval": "3000"
            },
            "extendParam": {
                "waitCrtUrlFinish": "1"
            }
        }
    ]
}

Body Parameters

list Object Parameters

src Object Parameters

forward Object Parameters

Note: Only the RTMP protocol is supported for forwarding destinations.

fops Object Parameters (Transcoding)

extendParam Object Parameters

Note on Parameter Precedence:
When end (in the list object), loop (in extendParam), and relofftime (in the src object) are all specified for a task, they are prioritized in the following order: end > loop > relofftime. The task will stop based on the highest-precedence parameter that is met.

API Response

The API returns a standard HTTP status code and a JSON body with a business-level status.

Sample Success Response:

{
    "http_code": "200",
    "msg": "receive task success!",
    "call_time": 1479952114000
}

Common HTTP Status Codes:

• 200 OK: Request accepted. Check the JSON body for the business-level result.
• 400 Bad Request: The request is malformed (e.g., invalid JSON, missing required fields).
• 403 Forbidden: Authentication failed (e.g., incorrect k signature, invalid r value, rate limit exceeded).
• 5xx Server Error: An unexpected error occurred on the server.

Business-Level http_code in JSON Body:

Task Query

This endpoint allows you to retrieve the status and details of tasks.

• HTTP Method: GET
• Endpoint: http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action

Example Request URL:

http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action?n=test&r=1741165183&k=a6edsa3c30d64e172b52136ba493ad1f&id=task_unique_id_001

Query Parameters

Note: At least one of id, src, or forward must be provided.

Query Response Body

Sample Query Response:

{
    "total": 1,
    "pageNo": 1,
    "pageSize": 100,
    "list": [
        {
            "id": "task_unique_id_001",
            "type": "live",
            "src": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
            "forward": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
            "cmd": "1",
            "code": "0",
            "msg": "Start pushing!",
            "startTime": "2025-03-05 16:05:12",
            "endTime": ""
        }
    ]
}

Callbacks

If a transcallbackurl is provided in the task creation request, the system will send POST requests with a JSON payload to that URL to notify you of task status changes.

Sample Callback Body:

{
    "id": "task_unique_id_001",
    "srcurl": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
    "forwardurl": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
    "cmd": "1",
    "code": "0",
    "msg": "Start pushing!",
    "event_time": 1600402486054
}

Callback code and msg Reference

Important Notes

1. Task Lifetime:

   • Real-time: If start and end are omitted, the task runs until cmd=2 is called or the source stream is disconnected.
   • Scheduled: If start and end are provided, the task runs within that window. It can still be stopped early with cmd=2.

2. Time Constraints:

   • The duration between a specified start and end time must be at least 5 minutes.
   • The end time must be in the future.

3. Transcoding: If you set any transcoding parameters in fops (like bps, res, or fps), you must also specify the vcodec.

4. Updating a Task (cmd=3): This command is used to update the source (src) for a task that is already running. You can also include fops and extendParam in the update request. Note that if a scheduled task has not yet started, you must first cancel it (cmd=2) and then create a new one with the updated configuration.

5. Resuming a Task (cmd=5): This command resumes a stopped task. It can be used within 48 hours of a task stopping. There are two stop scenarios with different resume behaviors:

   • Natural Stop: Occurs when all files in the src list have finished playing. Resuming with cmd=5 will restart the task from the beginning of the first file in the list.

   • Manual Stop: Occurs when a task is stopped with a cmd=2 command. Resuming with cmd=5 will continue from the point of interruption.

     The resume request ignores fops and extendParam; it only requires the id, src, and forward parameters to match the original task. Use resetUrl to specify a new destination if needed.

6. Stopping a Task (cmd=2):

   • This command stops forwarding for a given task. The id must match the running task.
   • To stop forwarding to a specific destination (if a task has multiple), include only that destination’s URL in the forward array of the stop request.
   • To stop the entire task, the forward list in your cmd=2 request should ideally include all currently active forwarding URLs for that task, or match the complete forward list provided when the task was initially created or last updated.
   • The URLs in the forward array of a stop request must exactly match the URL(s) that were used when the task was created (cmd=1) or last modified (cmd=3).
   • A task is considered fully terminated only when all its associated forwarding streams have been successfully stopped.

7. Rate Limiting: Be mindful of the API call frequency limit (typically 100 calls per 5 minutes). Exceeding this limit will result in a 403 Forbidden error.

8. Parameter Formatting: Note the difference in format: src and forward are JSON arrays in the API request, but are delivered as stringified JSON in the srcurl and forwardurl fields of callback messages.