Quickstart
You send one file of requests and get one file of results. The code below uses the OpenAI SDK, and the steps after step 2 follow on from each other.
1. Get a key
Sign in with your email address. You get a code by email. Your first sign-in shows your API key once, so copy it. You can make more keys later on the Keys page. Replace YOUR_HYFER_API_KEY in the code with your key.
You add credit before a batch can start. Each batch checks your balance when you create it.
2. Install the OpenAI SDK
pip install openai
npm install openai
# curl needs no install.
3. Upload a file
The file has one request on each line. The batch file page shows the lines. The purpose is always batch.
from openai import OpenAI
client = OpenAI(
base_url="https://api.gethyfer.com/api/v1",
api_key="YOUR_HYFER_API_KEY",
)
# Upload the file.
input_file = client.files.create(
file=open("requests.jsonl", "rb"),
purpose="batch",
)
print(input_file.id)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.gethyfer.com/api/v1",
apiKey: "YOUR_HYFER_API_KEY",
});
// Upload the file.
const inputFile = await client.files.create({
file: fs.createReadStream("requests.jsonl"),
purpose: "batch",
});
process.stdout.write(`${inputFile.id}\n`);
# The answer holds the file ID.
curl https://api.gethyfer.com/api/v1/files \
-H "Authorization: Bearer YOUR_HYFER_API_KEY" \
-F purpose=batch \
-F file=@requests.jsonl
4. Create a batch
The endpoint is /v1/chat/completions and the window is 24h. If the file has a bad line, the batch has the status failed and its errors field says which lines. See Errors.
# Create the batch.
batch = client.batches.create(
input_file_id=input_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(batch.id, batch.status)
// Create the batch.
let batch = await client.batches.create({
input_file_id: inputFile.id,
endpoint: "/v1/chat/completions",
completion_window: "24h",
});
process.stdout.write(`${batch.id} ${batch.status}\n`);
# Use the file ID from step 3. The answer holds the batch ID.
curl https://api.gethyfer.com/api/v1/batches \
-H "Authorization: Bearer YOUR_HYFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input_file_id": "FILE_ID", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'
5. Wait for the batch
A batch ends within 24 hours. Check its status from time to time.
# Wait until the batch ends.
import time
while batch.status in ("validating", "in_progress", "finalizing", "cancelling"):
time.sleep(60)
batch = client.batches.retrieve(batch.id)
print(batch.status, batch.request_counts)
// Wait until the batch ends.
while (["validating", "in_progress", "finalizing", "cancelling"].includes(batch.status)) {
await new Promise((resolve) => setTimeout(resolve, 60_000));
batch = await client.batches.retrieve(batch.id);
}
process.stdout.write(`${batch.status} ${JSON.stringify(batch.request_counts)}\n`);
# Repeat until "status" is completed, failed, expired or cancelled.
curl https://api.gethyfer.com/api/v1/batches/BATCH_ID \
-H "Authorization: Bearer YOUR_HYFER_API_KEY"
6. Download the result
A finished batch has an output file for the lines that worked and an error file for the lines that did not. The batch file page shows both.
# Download the result file, and the error file if there is one.
if batch.output_file_id:
print(client.files.content(batch.output_file_id).text)
if batch.error_file_id:
print(client.files.content(batch.error_file_id).text)
// Download the result file, and the error file if there is one.
if (batch.output_file_id) {
process.stdout.write(await (await client.files.content(batch.output_file_id)).text());
}
if (batch.error_file_id) {
process.stdout.write(await (await client.files.content(batch.error_file_id)).text());
}
# Use "output_file_id" and "error_file_id" from the last answer.
curl https://api.gethyfer.com/api/v1/files/OUTPUT_FILE_ID/content \
-H "Authorization: Bearer YOUR_HYFER_API_KEY" \
-o output.jsonl